Tree

Tree renders nested data as one accessible tree view. Selection and expansion use stable item keys, so the data may be replaced after an API request without losing state.

The component owns the flat role="tree" structure, roving focus, keyboard navigation, ARIA hierarchy metadata, and optional virtualization. The application keeps control of data fetching and item content.

Anatomy

• #item: Replaces the generated content inside every row while retaining tree semantics and selection styling.
• #item-[name]: Replaces generated content for items whose slot accessor resolves to that name.
• #toggle: Branch expand/collapse control.
• #indicator: Selection indicator, including indeterminate state.
• #icon: File, folder, or domain-specific icon.
• #label: Item content, including optional supporting text.
• #trailing: Metadata or actions at the end of a row.
• #loading: Loading row shown under an expanded lazy branch.
• #empty: Empty state when no items are available.

Every item slot receives item, normalized node state, node actions, toggleProps, and the tree controller.

Usage

<script setup lang="ts">
import type { TreeKey, TreeSelection } from "akaza-ui";
import { Tree } from "akaza-ui";
import { ref } from "vue";

const selected = ref<TreeSelection>("button");
const expanded = ref<TreeKey[]>(["src"]);
const items = [
  {
    id: "src",
    label: "src",
    children: [
      { id: "button", label: "Button.vue" },
      { id: "tree", label: "Tree.vue" },
    ],
  },
  { id: "package", label: "package.json" },
];
</script>

<template>
  <Tree
    v-model="selected"
    v-model:expanded="expanded"
    :items="items"
    item-key="id"
    aria-label="Project files"
  />
</template>

Examples

Lazy children

Mark unloaded branches with hasChildren. When a branch expands, fetch its children, replace the corresponding item, and remove its key from loadingKeys.

<script setup lang="ts">
import type { TreeExpandedChangeEventDetails, TreeKey } from "akaza-ui";
import { ref } from "vue";

const items = ref([{ id: "users", label: "Users", lazy: true }]);
const expanded = ref<TreeKey[]>([]);
const loadingKeys = ref<TreeKey[]>([]);

async function onExpandedChange(_keys: TreeKey[], details: TreeExpandedChangeEventDetails<(typeof items.value)[number]>) {
  if (!details.expanded || !details.item.lazy) return;
  loadingKeys.value = [...loadingKeys.value, details.key];
  const children = await fetch(`/api/tree/${details.key}`).then(response => response.json());
  items.value = items.value.map(item => item.id === details.key ? { ...item, children } : item);
  loadingKeys.value = loadingKeys.value.filter(key => key !== details.key);
}
</script>

<template>
  <Tree
    v-model:expanded="expanded"
    :items="items"
    item-key="id"
    :has-children="item => item.lazy || Boolean(item.children?.length)"
    :loading-keys="loadingKeys"
    @expanded-change="onExpandedChange"
  />
</template>

Tree does not cache or fetch data. This keeps request deduplication, retries, authorization, and cache policy in the application.

Multiple selection and propagation

Use selectionPropagation="both" when selecting a branch should select its descendants and fully selected descendants should select their ancestors.

<template>
  <Tree
    v-model="permissions"
    :items="permissionItems"
    item-key="id"
    selection-mode="multiple"
    selection-propagation="both"
  >
    <template #indicator="{ node }">
      <span>{{ node.isIndeterminate ? "-" : node.isSelected ? "x" : "" }}</span>
    </template>
  </Tree>
</template>

Propagation modes are none, down, up, and both. Disabled and non-selectable items are excluded.

For leaf-only selection, resolve selectableKey from the item rather than adding another selection mode:

<Tree
  :items="items"
  item-key="id"
  :selectable-key="item => item.type === 'file'"
/>

Icons and row actions

Use the granular slots for content that should keep the built-in row behavior. Use #item only when replacing the complete row.

<template>
  <Tree :items="items" item-key="id">
    <template #icon="{ item, node }">
      <FolderOpenIcon v-if="item.type === 'folder' && node.isExpanded" />
      <FolderIcon v-else-if="item.type === 'folder'" />
      <FileIcon v-else />
    </template>

    <template #trailing="{ item }">
      <button type="button" data-akaza-tree-ignore @click="rename(item)">Rename</button>
    </template>
  </Tree>
</template>

Interactive controls in a row do not activate or select the node. Add data-akaza-tree-ignore to a custom interactive wrapper that is not a native button, link, input, select, textarea, or editable element.

The data contract has no built-in description field. Render a title, description, or any other item content through #label:

<Tree :items="items" item-key="id">
  <template #label="{ item }">
    <span class="grid">
      <span>{{ item.title }}</span>
      <span class="text-sm text-neutral-500">{{ item.description }}</span>
    </span>
  </template>
</Tree>

Row expansion

Clicking a branch row toggles it by default. Native controls and elements marked with data-akaza-tree-ignore do not toggle the branch. Restrict expansion to the generated toggle button when row clicks perform another action:

<Tree :expand-on-click="false" />

Selection highlight

Selection semantics always stay on the complete treeitem. selectionHighlight only controls the visual highlight boundary:

<Tree selection-highlight="full" />
<Tree selection-highlight="indented" />
<Tree selection-highlight="label" />

• full spans the available row width.
• indented starts at the node depth. This is the default.
• label follows the label content.

Style all three modes with ui.selection. Its data-akaza-selection-highlight value identifies the active boundary.

Expansion motion

Children fade and move a few pixels as branches open and close. Existing rows also move into their new position. Disable this behavior when another animation system owns the rows:

<Tree :transition="false" />

Motion is disabled automatically for virtualized trees and reduced to an effectively immediate transition when the user prefers reduced motion.

Activation and detail loading

activate runs on row click, touch, or Enter. Use it to load a detail panel independently from branch expansion.

<template>
  <Tree
    :items="items"
    item-key="id"
    @activate="(item, details) => openDetails(item, details.reason)"
  />
</template>

Virtualization

Virtualization keeps only the visible rows mounted. Set a fixed row height and viewport height.

<template>
  <Tree
    :items="largeTree"
    item-key="id"
    :virtualize="{ height: 320, itemHeight: 36, overscan: 6 }"
  />
</template>

Keep custom rows and loading content compatible with itemHeight; variable-height virtualization is not supported.

API Reference

Models

Props

TreeVirtualOptions accepts height, itemHeight, and overscan numbers.

Emits

Event details include key, item, reason, the original event when available, and cancel(). Calling cancel() in a change event prevents its model update.

Slots

node exposes key, parent, depth, sibling position, label, and branch, expansion, selection, indeterminate, focus, disabled, selectable, and loading state.

Exposed Methods

The tree controller available to slots exposes the same methods plus reactive visible nodes, selected items, models, and focused key.

Item Shape

Default accessors recognize these keys. Accessor props support any data shape.

UI Options

Styling Hooks

Plain class applies to the root. Use ui.viewport, ui.item, and the granular part keys for generated content. Items expose --akaza-tree-depth and the computed --akaza-tree-indent-offset.

Keyboard

Horizontal orientation maps movement to Left/Right and expansion to Down/Up. One visible enabled item participates in the page tab order.

In multiple mode, Shift + click selects the visible range from the last selection anchor. Ctrl / Cmd + Shift + click adds that range to the current selection.