Tree View

A hierarchical list where items with children can be expanded or collapsed. Common uses include file browsers, navigation menus, and organizational charts.

🤖 AI Implementation Guide

React Vue Svelte Astro

Demo

Single-Select with Activation

Documents
Images
readme.md

Activated: Select a node with Enter, Space, or Click

Multi-Select

Documents
Images
readme.md

With Disabled Nodes

Accessible Folder
Restricted Folder
public.txt

Accessibility Features

WAI-ARIA Roles

Role	Target Element	Description
`tree`	Container (`<ul>`)	The tree widget container
`treeitem`	Each node (`<li>`)	Individual tree nodes (both parent and leaf)
`group`	Child container (`<ul>`)	Container for child nodes of an expanded parent

WAI-ARIA tree role (opens in new tab)

WAI-ARIA Properties (Tree Container)

Attribute	Values	Required	Description
`role="tree"`	-	Yes	Identifies the container as a tree widget
`aria-label`	String	Yes*	Accessible name for the tree
`aria-labelledby`	ID reference	Yes*	Alternative to aria-label (takes precedence)
`aria-multiselectable`	`true`	No	Only present for multi-select mode

* Either aria-label or aria-labelledby is required.

WAI-ARIA States (Tree Items)

Attribute	Values	Required	Description
`aria-expanded`	`true` \| `false`	Yes*	Present on parent nodes only. Indicates expansion state.
`aria-selected`	`true` \| `false`	Yes**	All treeitems must have this (selected=true, others=false)
`aria-disabled`	`true`	No	Indicates the node is disabled
`tabindex`	`0` \| `-1`	Yes	Roving tabindex for focus management

* Required on parent nodes. Leaf nodes must NOT have aria-expanded.
** When selection is supported, ALL treeitems must have aria-selected.

Keyboard Support

Navigation

Key	Action
`↓`	Move focus to next visible node
`↑`	Move focus to previous visible node
`→`	Closed parent: expand / Open parent: move to first child / Leaf: no action
`←`	Open parent: collapse / Child or closed parent: move to parent / Root: no action
`Home`	Move focus to first node
`End`	Move focus to last visible node
`Enter`	Select and activate node (see Selection section below)
`*`	Expand all siblings at current level
Type characters	Move focus to next visible node starting with that character

Selection (Single-Select Mode)

Key	Action
`↓` / `↑`	Move focus only (selection does NOT follow focus)
`Enter`	Select focused node and activate (fire onActivate callback)
`Space`	Select focused node and activate (fire onActivate callback)
Click	Select clicked node and activate (fire onActivate callback)

Selection (Multi-Select Mode)

Key	Action
`Space`	Toggle selection of focused node
`Ctrl` + `Space`	Toggle selection without moving focus
`Shift` + `↓` / `↑`	Extend selection range from anchor
`Shift` + `Home`	Extend selection to first node
`Shift` + `End`	Extend selection to last visible node
`Ctrl` + `A`	Select all visible nodes

Focus Management

This component uses roving tabindex for focus management:

Only one node has tabindex="0" (the focused node)
All other nodes have tabindex="-1"
Tree is a single Tab stop (Tab enters tree, Shift+Tab exits)
Focus moves only among visible nodes (collapsed children are skipped)
When a parent is collapsed while a child has focus, focus moves to the parent

Disabled Nodes

Have aria-disabled="true"
Are focusable (included in keyboard navigation)
Cannot be selected or activated
Cannot be expanded or collapsed if a parent node
Visually distinct (e.g., grayed out)

Source Code

TreeView.svelte

<script lang="ts">
  import { onMount, onDestroy, tick } from 'svelte';

  export interface TreeNode {
    id: string;
    label: string;
    children?: TreeNode[];
    disabled?: boolean;
  }

  interface TreeViewProps {
    nodes: TreeNode[];
    multiselectable?: boolean;
    defaultSelectedIds?: string[];
    selectedIds?: string[];
    defaultExpandedIds?: string[];
    expandedIds?: string[];
    ariaLabel?: string;
    ariaLabelledby?: string;
    typeAheadTimeout?: number;
    onSelectionChange?: (selectedIds: string[]) => void;
    onExpandedChange?: (expandedIds: string[]) => void;
    onActivate?: (nodeId: string) => void;
    class?: string;
  }

  interface FlatNode {
    node: TreeNode;
    depth: number;
    parentId: string | null;
    hasChildren: boolean;
  }

  let {
    nodes = [],
    multiselectable = false,
    defaultSelectedIds = [],
    selectedIds: controlledSelectedIds = undefined,
    defaultExpandedIds = [],
    expandedIds: controlledExpandedIds = undefined,
    ariaLabel = undefined,
    ariaLabelledby = undefined,
    typeAheadTimeout = 500,
    onSelectionChange = () => {},
    onExpandedChange = () => {},
    onActivate = () => {},
    class: className = '',
  }: TreeViewProps = $props();

  let instanceId = $state('');
  let nodeRefs = new Map<string, HTMLLIElement>();
  let typeAheadBuffer = $state('');
  let typeAheadTimeoutId: number | null = null;
  let selectionAnchor = $state('');
  let focusedIdRef = $state('');

  // Internal state
  let internalExpandedIds = $state<Set<string>>(new Set());
  let internalSelectedIds = $state<Set<string>>(new Set());
  let focusedId = $state('');

  onMount(() => {
    instanceId = `treeview-${Math.random().toString(36).slice(2, 11)}`;
  });

  // Cleanup type-ahead timeout on destroy
  onDestroy(() => {
    if (typeAheadTimeoutId !== null) {
      clearTimeout(typeAheadTimeoutId);
    }
  });

  // Flatten tree for navigation
  function flattenTree(
    treeNodes: TreeNode[],
    depth: number = 0,
    parentId: string | null = null
  ): FlatNode[] {
    const result: FlatNode[] = [];
    for (const node of treeNodes) {
      const hasChildren = Boolean(node.children && node.children.length > 0);
      result.push({ node, depth, parentId, hasChildren });
      if (node.children) {
        result.push(...flattenTree(node.children, depth + 1, node.id));
      }
    }
    return result;
  }

  let allNodes = $derived(flattenTree(nodes));

  let nodeMap = $derived.by(() => {
    const map = new Map<string, FlatNode>();
    for (const flatNode of allNodes) {
      map.set(flatNode.node.id, flatNode);
    }
    return map;
  });

  // Expansion state (controlled or uncontrolled)
  let expandedIds = $derived(
    controlledExpandedIds ? new Set(controlledExpandedIds) : internalExpandedIds
  );

  // Selection state (controlled or uncontrolled)
  let selectedIds = $derived(
    controlledSelectedIds ? new Set(controlledSelectedIds) : internalSelectedIds
  );

  // Visible nodes (respecting expansion state)
  let visibleNodes = $derived.by(() => {
    const result: FlatNode[] = [];
    const collapsedParents = new Set<string>();

    for (const flatNode of allNodes) {
      let isHidden = false;
      let currentParentId = flatNode.parentId;

      while (currentParentId) {
        if (collapsedParents.has(currentParentId) || !expandedIds.has(currentParentId)) {
          isHidden = true;
          break;
        }
        const parent = nodeMap.get(currentParentId);
        currentParentId = parent?.parentId ?? null;
      }

      if (!isHidden) {
        result.push(flatNode);
        if (flatNode.hasChildren && !expandedIds.has(flatNode.node.id)) {
          collapsedParents.add(flatNode.node.id);
        }
      }
    }
    return result;
  });

  let visibleIndexMap = $derived.by(() => {
    const map = new Map<string, number>();
    visibleNodes.forEach((flatNode, index) => map.set(flatNode.node.id, index));
    return map;
  });

  let containerClass = $derived(`apg-treeview ${className}`.trim());

  // Initialize state
  $effect(() => {
    if (allNodes.length > 0 && internalSelectedIds.size === 0 && internalExpandedIds.size === 0) {
      // Initialize expansion
      internalExpandedIds = new Set(defaultExpandedIds);

      // Initialize selection (filter out disabled nodes)
      if (defaultSelectedIds.length > 0) {
        const validIds = defaultSelectedIds.filter((id) => {
          const flatNode = nodeMap.get(id);
          return flatNode && !flatNode.node.disabled;
        });
        if (validIds.length > 0) {
          internalSelectedIds = new Set(validIds);
        }
      }
      // No auto-selection - user must explicitly select via Enter/Space/Click

      // Initialize focus
      const firstSelected = [...selectedIds][0];
      if (firstSelected) {
        const flatNode = nodeMap.get(firstSelected);
        if (flatNode && !flatNode.node.disabled) {
          focusedId = firstSelected;
          focusedIdRef = firstSelected;
          selectionAnchor = firstSelected;
          return;
        }
      }
      const firstEnabled = allNodes.find((fn) => !fn.node.disabled);
      if (firstEnabled) {
        focusedId = firstEnabled.node.id;
        focusedIdRef = firstEnabled.node.id;
        selectionAnchor = firstEnabled.node.id;
      }
    }
  });

  // Reactive guard: ensure focusedId and selectionAnchor remain valid when visibility changes
  $effect(() => {
    // Skip during initialization
    if (!focusedId) return;

    // Check if focusedId is still visible
    if (!visibleIndexMap.has(focusedId)) {
      // Find first visible non-disabled node
      const firstEnabled = visibleNodes.find((fn) => !fn.node.disabled);
      if (firstEnabled) {
        focusedId = firstEnabled.node.id;
        focusedIdRef = firstEnabled.node.id;
        selectionAnchor = firstEnabled.node.id;
        // Focus moves but selection does not change automatically
      }
    }

    // Check if selectionAnchor is still valid
    if (selectionAnchor && !visibleIndexMap.has(selectionAnchor)) {
      selectionAnchor = focusedId;
    }
  });

  // Action to track node element references
  function trackNodeRef(node: HTMLLIElement, nodeId: string) {
    nodeRefs.set(nodeId, node);
    return {
      destroy() {
        nodeRefs.delete(nodeId);
      },
    };
  }

  function updateExpandedIds(newExpandedIds: Set<string>) {
    if (!controlledExpandedIds) {
      internalExpandedIds = newExpandedIds;
    }
    onExpandedChange([...newExpandedIds]);
  }

  function updateSelectedIds(newSelectedIds: Set<string>) {
    if (!controlledSelectedIds) {
      internalSelectedIds = newSelectedIds;
    }
    onSelectionChange([...newSelectedIds]);
  }

  function setFocusedId(nodeId: string) {
    focusedIdRef = nodeId;
    focusedId = nodeId;
  }

  async function applyDomFocus(nodeId: string) {
    await tick();
    nodeRefs.get(nodeId)?.focus();
  }

  function focusNode(nodeId: string) {
    setFocusedId(nodeId);
    applyDomFocus(nodeId);
  }

  function focusByIndex(index: number) {
    const flatNode = visibleNodes[index];
    if (flatNode) {
      focusNode(flatNode.node.id);
    }
  }

  // Expansion helpers
  function expandNode(nodeId: string) {
    const flatNode = nodeMap.get(nodeId);
    if (!flatNode?.hasChildren || flatNode.node.disabled) return;
    if (expandedIds.has(nodeId)) return;

    const newExpanded = new Set(expandedIds);
    newExpanded.add(nodeId);
    updateExpandedIds(newExpanded);
  }

  function collapseNode(nodeId: string) {
    const flatNode = nodeMap.get(nodeId);
    if (!flatNode?.hasChildren || flatNode.node.disabled) return;
    if (!expandedIds.has(nodeId)) return;

    const newExpanded = new Set(expandedIds);
    newExpanded.delete(nodeId);
    updateExpandedIds(newExpanded);

    // If a child of this node was focused, move focus to the collapsed parent
    const currentFocused = nodeMap.get(focusedId);
    if (currentFocused) {
      let parentId = currentFocused.parentId;
      while (parentId) {
        if (parentId === nodeId) {
          focusNode(nodeId);
          break;
        }
        const parent = nodeMap.get(parentId);
        parentId = parent?.parentId ?? null;
      }
    }
  }

  function expandAllSiblings(nodeId: string) {
    const flatNode = nodeMap.get(nodeId);
    if (!flatNode) return;

    const newExpanded = new Set(expandedIds);
    for (const fn of allNodes) {
      if (fn.parentId === flatNode.parentId && fn.hasChildren && !fn.node.disabled) {
        newExpanded.add(fn.node.id);
      }
    }
    updateExpandedIds(newExpanded);
  }

  // Selection helpers
  function selectNode(nodeId: string) {
    const flatNode = nodeMap.get(nodeId);
    if (flatNode?.node.disabled) return;

    if (multiselectable) {
      const newSelected = new Set(selectedIds);
      if (newSelected.has(nodeId)) {
        newSelected.delete(nodeId);
      } else {
        newSelected.add(nodeId);
      }
      updateSelectedIds(newSelected);
    } else {
      updateSelectedIds(new Set([nodeId]));
    }
  }

  function selectRange(fromId: string, toId: string) {
    const fromIndex = visibleIndexMap.get(fromId) ?? 0;
    const toIndex = visibleIndexMap.get(toId) ?? 0;
    const start = Math.min(fromIndex, toIndex);
    const end = Math.max(fromIndex, toIndex);

    const newSelected = new Set(selectedIds);
    for (let i = start; i <= end; i++) {
      const flatNode = visibleNodes[i];
      if (flatNode && !flatNode.node.disabled) {
        newSelected.add(flatNode.node.id);
      }
    }
    updateSelectedIds(newSelected);
  }

  function selectAllVisible() {
    const newSelected = new Set<string>();
    for (const flatNode of visibleNodes) {
      if (!flatNode.node.disabled) {
        newSelected.add(flatNode.node.id);
      }
    }
    updateSelectedIds(newSelected);
  }

  // Type-ahead
  function handleTypeAhead(char: string) {
    if (visibleNodes.length === 0) return;

    if (typeAheadTimeoutId !== null) {
      clearTimeout(typeAheadTimeoutId);
    }

    typeAheadBuffer += char.toLowerCase();
    const buffer = typeAheadBuffer;

    const isSameChar = buffer.length > 1 && buffer.split('').every((c) => c === buffer[0]);

    const currentIndex = visibleIndexMap.get(focusedId) ?? 0;
    let startIndex: number;
    let searchStr: string;

    if (isSameChar) {
      typeAheadBuffer = buffer[0];
      startIndex = (currentIndex + 1) % visibleNodes.length;
      searchStr = buffer[0];
    } else if (buffer.length === 1) {
      startIndex = (currentIndex + 1) % visibleNodes.length;
      searchStr = buffer;
    } else {
      startIndex = currentIndex;
      searchStr = buffer;
    }

    for (let i = 0; i < visibleNodes.length; i++) {
      const index = (startIndex + i) % visibleNodes.length;
      const flatNode = visibleNodes[index];
      // Skip disabled nodes in type-ahead
      if (flatNode.node.disabled) continue;
      if (flatNode.node.label.toLowerCase().startsWith(searchStr)) {
        focusNode(flatNode.node.id);
        // Update anchor in multiselect mode
        if (multiselectable) {
          selectionAnchor = flatNode.node.id;
        }
        // Type-ahead only moves focus, does not change selection
        break;
      }
    }

    typeAheadTimeoutId = window.setTimeout(() => {
      typeAheadBuffer = '';
      typeAheadTimeoutId = null;
    }, typeAheadTimeout);
  }

  function handleNodeClick(nodeId: string) {
    const flatNode = nodeMap.get(nodeId);
    if (!flatNode || flatNode.node.disabled) return;

    focusNode(nodeId);

    // Toggle expansion for parent nodes
    if (flatNode.hasChildren) {
      if (expandedIds.has(nodeId)) {
        collapseNode(nodeId);
      } else {
        expandNode(nodeId);
      }
    }

    // Select and activate
    if (multiselectable) {
      selectNode(nodeId);
      selectionAnchor = nodeId;
    } else {
      updateSelectedIds(new Set([nodeId]));
    }
    onActivate(nodeId);
  }

  function handleNodeFocus(nodeId: string) {
    focusedIdRef = nodeId;
    focusedId = nodeId;
  }

  // Determine if key should be handled
  function shouldHandleKey(key: string, ctrlKey: boolean, metaKey: boolean): boolean {
    const handledKeys = [
      'ArrowDown',
      'ArrowUp',
      'ArrowRight',
      'ArrowLeft',
      'Home',
      'End',
      'Enter',
      ' ',
      '*',
    ];
    if (handledKeys.includes(key)) return true;
    if (key.length === 1 && !ctrlKey && !metaKey) return true;
    if ((key === 'a' || key === 'A') && (ctrlKey || metaKey) && multiselectable) return true;
    return false;
  }

  function handleKeyDown(event: KeyboardEvent) {
    if (visibleNodes.length === 0) return;

    const { key, shiftKey, ctrlKey, metaKey } = event;

    // Call preventDefault synchronously for all handled keys
    if (shouldHandleKey(key, ctrlKey, metaKey)) {
      event.preventDefault();
    }

    const actualFocusedId = focusedIdRef;
    const currentIndex = visibleIndexMap.get(actualFocusedId) ?? 0;
    const currentFlatNode = visibleNodes[currentIndex];

    switch (key) {
      case 'ArrowDown': {
        if (currentIndex < visibleNodes.length - 1) {
          const nextIndex = currentIndex + 1;
          focusByIndex(nextIndex);
          const nextNode = visibleNodes[nextIndex];
          if (multiselectable && shiftKey) {
            selectRange(selectionAnchor, nextNode.node.id);
          } else if (multiselectable) {
            selectionAnchor = nextNode.node.id;
          }
          // Single-select: focus moves but selection does not change
        }
        break;
      }

      case 'ArrowUp': {
        if (currentIndex > 0) {
          const prevIndex = currentIndex - 1;
          focusByIndex(prevIndex);
          const prevNode = visibleNodes[prevIndex];
          if (multiselectable && shiftKey) {
            selectRange(selectionAnchor, prevNode.node.id);
          } else if (multiselectable) {
            selectionAnchor = prevNode.node.id;
          }
          // Single-select: focus moves but selection does not change
        }
        break;
      }

      case 'ArrowRight': {
        if (!currentFlatNode) break;

        if (currentFlatNode.hasChildren && !currentFlatNode.node.disabled) {
          if (!expandedIds.has(actualFocusedId)) {
            expandNode(actualFocusedId);
          } else {
            const nextIndex = currentIndex + 1;
            if (nextIndex < visibleNodes.length) {
              const nextNode = visibleNodes[nextIndex];
              if (nextNode.parentId === actualFocusedId) {
                focusByIndex(nextIndex);
                // Update anchor on lateral navigation in multiselect
                if (multiselectable) {
                  selectionAnchor = nextNode.node.id;
                }
                // Single-select: focus moves but selection does not change
              }
            }
          }
        }
        break;
      }

      case 'ArrowLeft': {
        if (!currentFlatNode) break;

        if (
          currentFlatNode.hasChildren &&
          expandedIds.has(actualFocusedId) &&
          !currentFlatNode.node.disabled
        ) {
          collapseNode(actualFocusedId);
        } else if (currentFlatNode.parentId) {
          focusNode(currentFlatNode.parentId);
          // Update anchor on lateral navigation in multiselect
          if (multiselectable) {
            selectionAnchor = currentFlatNode.parentId;
          }
          // Single-select: focus moves but selection does not change
        }
        break;
      }

      case 'Home': {
        focusByIndex(0);
        const firstNode = visibleNodes[0];
        if (multiselectable && shiftKey) {
          selectRange(selectionAnchor, firstNode.node.id);
        } else if (multiselectable) {
          selectionAnchor = firstNode.node.id;
        }
        // Single-select: focus moves but selection does not change
        break;
      }

      case 'End': {
        const lastIndex = visibleNodes.length - 1;
        focusByIndex(lastIndex);
        const lastNode = visibleNodes[lastIndex];
        if (multiselectable && shiftKey) {
          selectRange(selectionAnchor, lastNode.node.id);
        } else if (multiselectable) {
          selectionAnchor = lastNode.node.id;
        }
        // Single-select: focus moves but selection does not change
        break;
      }

      case 'Enter': {
        if (currentFlatNode && !currentFlatNode.node.disabled) {
          // Select the node (single-select replaces, multi-select behavior via selectNode)
          if (multiselectable) {
            selectNode(actualFocusedId);
            selectionAnchor = actualFocusedId;
          } else {
            updateSelectedIds(new Set([actualFocusedId]));
          }
          // Fire activation callback
          onActivate(actualFocusedId);
        }
        break;
      }

      case ' ': {
        if (currentFlatNode && !currentFlatNode.node.disabled) {
          if (multiselectable) {
            selectNode(actualFocusedId);
            // Ctrl+Space: toggle without updating anchor
            // Space alone: update anchor for subsequent Shift+Arrow operations
            if (!ctrlKey) {
              selectionAnchor = actualFocusedId;
            }
          } else {
            // Single-select: Space selects and activates (same as Enter)
            updateSelectedIds(new Set([actualFocusedId]));
            onActivate(actualFocusedId);
          }
        }
        break;
      }

      case '*': {
        expandAllSiblings(actualFocusedId);
        break;
      }

      case 'a':
      case 'A': {
        if ((ctrlKey || metaKey) && multiselectable) {
          selectAllVisible();
        } else if (!ctrlKey && !metaKey) {
          handleTypeAhead(key);
        }
        break;
      }

      default: {
        if (key.length === 1 && !ctrlKey && !metaKey) {
          handleTypeAhead(key);
        }
      }
    }
  }

  function getNodeClass(node: TreeNode, hasChildren: boolean): string {
    const classes = ['apg-treeview-item'];
    if (selectedIds.has(node.id)) {
      classes.push('apg-treeview-item--selected');
    }
    if (node.disabled) {
      classes.push('apg-treeview-item--disabled');
    }
    if (hasChildren) {
      classes.push('apg-treeview-item--parent');
    } else {
      classes.push('apg-treeview-item--leaf');
    }
    return classes.join(' ');
  }
</script>

{#snippet renderNode(node: TreeNode, depth: number)}
  {@const hasChildren = Boolean(node.children && node.children.length > 0)}
  {@const isExpanded = expandedIds.has(node.id)}
  {@const isSelected = selectedIds.has(node.id)}
  {@const isFocused = focusedId === node.id}
  {@const labelId = `${instanceId}-label-${node.id}`}

  <!-- svelte-ignore a11y_click_events_have_key_events a11y_no_noninteractive_element_interactions -->
  <li
    use:trackNodeRef={node.id}
    role="treeitem"
    aria-labelledby={labelId}
    aria-expanded={hasChildren ? isExpanded : undefined}
    aria-selected={isSelected}
    aria-disabled={node.disabled || undefined}
    tabindex={isFocused ? 0 : -1}
    class={getNodeClass(node, hasChildren)}
    style="--depth: {depth}"
    onclick={(e) => {
      e.stopPropagation();
      handleNodeClick(node.id);
    }}
    onfocus={(e) => {
      if (e.target === e.currentTarget) {
        handleNodeFocus(node.id);
      }
    }}
  >
    <span class="apg-treeview-item-content">
      {#if hasChildren}
        <span class="apg-treeview-item-icon" aria-hidden="true">
          {isExpanded ? '\u25BC' : '\u25B6'}
        </span>
      {/if}
      <span id={labelId} class="apg-treeview-item-label">
        {node.label}
      </span>
    </span>
    {#if hasChildren && isExpanded && node.children}
      <ul role="group" class="apg-treeview-group">
        {#each node.children as child}
          {@render renderNode(child, depth + 1)}
        {/each}
      </ul>
    {/if}
  </li>
{/snippet}

<ul
  role="tree"
  aria-label={ariaLabel}
  aria-labelledby={ariaLabelledby}
  aria-multiselectable={multiselectable || undefined}
  class={containerClass}
  onkeydown={handleKeyDown}
>
  {#each nodes as node}
    {@render renderNode(node, 0)}
  {/each}
</ul>

Usage

Example

<script>
import TreeView from './TreeView.svelte';

const nodes = [
  {
    id: 'documents',
    label: 'Documents',
    children: [
      { id: 'report', label: 'report.pdf' },
      { id: 'notes', label: 'notes.txt' },
    ],
  },
  { id: 'readme', label: 'readme.md' },
];

function handleSelectionChange(event) {
  console.log('Selected:', event.detail);
}

function handleExpandedChange(event) {
  console.log('Expanded:', event.detail);
}

function handleActivate(event) {
  console.log('Activated:', event.detail);
}
</script>

<!-- Basic single-select -->
<TreeView
  {nodes}
  aria-label="File Explorer"
/>

<!-- With default expanded -->
<TreeView
  {nodes}
  aria-label="Files"
  defaultExpandedIds={['documents']}
/>

<!-- Multi-select mode -->
<TreeView
  {nodes}
  aria-label="Files"
  multiselectable
/>

<!-- With callbacks -->
<TreeView
  {nodes}
  aria-label="Files"
  onselectionchange={handleSelectionChange}
  onexpandedchange={handleExpandedChange}
  onactivate={handleActivate}
/>

API

TreeNode Interface

Property	Type	Required	Description
`id`	string	Yes	Unique identifier for the node
`label`	string	Yes	Display label for the node
`children`	TreeNode[]	No	Child nodes (makes this a parent node)
`disabled`	boolean	No	Prevents selection, activation, and expansion

Props

Prop	Type	Default	Description
`nodes`	TreeNode[]	Required	Array of tree nodes
`multiselectable`	boolean	false	Enable multi-select mode
`defaultSelectedIds`	string[]	[]	Initially selected node IDs (uncontrolled)
`selectedIds`	string[]	-	Currently selected node IDs (controlled)
`defaultExpandedIds`	string[]	[]	Initially expanded node IDs (uncontrolled)
`expandedIds`	string[]	-	Currently expanded node IDs (controlled)
`typeAheadTimeout`	number	500	Type-ahead buffer reset timeout (ms)
`aria-label`	string	-	Accessible label for the tree
`aria-labelledby`	string	-	ID of labeling element

Events

Event	Detail	Description
`onselectionchange`	string[]	Dispatched when selection changes
`onexpandedchange`	string[]	Dispatched when expansion state changes
`onactivate`	string	Dispatched when node is activated (Enter key)

Testing

Tests verify APG compliance for ARIA attributes, keyboard interactions, expansion/collapse behavior, selection models, and accessibility requirements.

Test Categories

High Priority: ARIA Structure

Test	Description
`role="tree"`	Container element has the tree role
`role="treeitem"`	Each node has the treeitem role
`role="group"`	Child containers have the group role
`aria-expanded (parent)`	Parent nodes have aria-expanded (true or false)
`aria-expanded (leaf)`	Leaf nodes do NOT have aria-expanded
`aria-selected`	All treeitems have aria-selected (true or false)
`aria-multiselectable`	Tree has aria-multiselectable="true" in multi-select mode
`aria-disabled`	Disabled nodes have aria-disabled="true"

High Priority: Accessible Name

Test	Description
`aria-label`	Tree has accessible name via aria-label
`aria-labelledby`	Tree can use aria-labelledby (takes precedence)

High Priority: Navigation

Test	Description
`ArrowDown`	Moves to next visible node
`ArrowUp`	Moves to previous visible node
`Home`	Moves to first node
`End`	Moves to last visible node
`Type-ahead`	Typing characters focuses matching visible node

High Priority: Expand/Collapse

Test	Description
`ArrowRight (closed parent)`	Expands the parent node
`ArrowRight (open parent)`	Moves to first child
`ArrowRight (leaf)`	Does nothing
`ArrowLeft (open parent)`	Collapses the parent node
`ArrowLeft (child/closed)`	Moves to parent node
`ArrowLeft (root)`	Does nothing
`* (asterisk)`	Expands all siblings at current level
`Enter`	Activates node (does NOT toggle expansion)

High Priority: Selection (Single-Select)

Test	Description
`Arrow navigation`	Selection follows focus (arrows change selection)
`Space`	Has no effect in single-select mode
`Only one selected`	Only one node can be selected at a time

High Priority: Selection (Multi-Select)

Test	Description
`Space`	Toggles selection of focused node
`Ctrl+Space`	Toggles selection without moving focus
`Shift+Arrow`	Extends selection range from anchor
`Shift+Home`	Extends selection to first node
`Shift+End`	Extends selection to last visible node
`Ctrl+A`	Selects all visible nodes
`Multiple selection`	Multiple nodes can be selected simultaneously

High Priority: Focus Management

Test	Description
`Single Tab stop`	Tree is a single Tab stop (Tab/Shift+Tab)
`tabindex="0"`	Focused node has tabindex="0"
`tabindex="-1"`	Other nodes have tabindex="-1"
`Skip collapsed`	Collapsed children are skipped during navigation
`Focus to parent`	Focus moves to parent when child's parent is collapsed

Medium Priority: Disabled Nodes

Test	Description
`Focusable`	Disabled nodes can receive focus
`Not selectable`	Disabled nodes cannot be selected
`Not expandable`	Disabled parent nodes cannot be expanded/collapsed
`Not activatable`	Enter key does not activate disabled nodes

Medium Priority: Type-Ahead

Test	Description
`Visible nodes only`	Type-ahead only searches visible nodes
`Cycle on repeat`	Repeated character cycles through matches
`Multi-character prefix`	Multiple characters form a search prefix
`Timeout reset`	Buffer resets after timeout (default 500ms)
`Skip disabled`	Type-ahead skips disabled nodes

Medium Priority: Mouse Interaction

Test	Description
`Click parent`	Toggles expansion and selects node
`Click leaf`	Selects the leaf node
`Click disabled`	Disabled nodes cannot be selected or expanded

Low Priority: Callbacks

Test	Description
`onSelectionChange`	Called with selected IDs when selection changes
`onExpandedChange`	Called with expanded IDs when expansion changes
`onActivate`	Called with node ID on Enter key

Testing Tools

React: React Testing Library (opens in new tab)
Vue: Vue Testing Library (opens in new tab)
Svelte: Svelte Testing Library (opens in new tab)
Astro: Vitest with JSDOM for Web Component unit tests
Accessibility: axe-core (opens in new tab)

Resources

WAI-ARIA APG: Tree View Pattern (opens in new tab)
APG Example: Navigation Treeview (opens in new tab)
AI Implementation Guide (llm.md) (opens in new tab) - ARIA specs, keyboard support, test checklist