APG Patterns
日本語 GitHub
日本語 GitHub

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
Vue

Demo

Single-Select with Activation

  • readme.md
Activated: Select a node with Enter, Space, or Click

Multi-Select

  • readme.md

With Disabled Nodes

  • 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.vue 
<template>
  <ul
    role="tree"
    :aria-label="ariaLabel"
    :aria-labelledby="ariaLabelledby"
    :aria-multiselectable="multiselectable || undefined"
    :class="containerClass"
    @keydown="handleKeyDown"
  >
    <TreeNode
      v-for="node in nodes"
      :key="node.id"
      :node="node"
      :depth="0"
      :instance-id="instanceId"
      :expanded-ids="expandedIds"
      :selected-ids="selectedIds"
      :focused-id="focusedId"
      :visible-index-map="visibleIndexMap"
      @node-click="handleNodeClick"
      @node-focus="handleNodeFocus"
      @set-ref="setNodeRef"
    />
  </ul>
</template>

<script setup lang="ts">
import { ref, computed, onMounted, nextTick } from 'vue';
import TreeNode from './TreeNode.vue';

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

export interface TreeViewProps {
  nodes: TreeNodeData[];
  multiselectable?: boolean;
  defaultSelectedIds?: string[];
  selectedIds?: string[];
  defaultExpandedIds?: string[];
  expandedIds?: string[];
  ariaLabel?: string;
  ariaLabelledby?: string;
  typeAheadTimeout?: number;
  className?: string;
}

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

const props = withDefaults(defineProps<TreeViewProps>(), {
  multiselectable: false,
  defaultSelectedIds: () => [],
  defaultExpandedIds: () => [],
  typeAheadTimeout: 500,
  className: '',
});

const emit = defineEmits<{
  selectionChange: [selectedIds: string[]];
  expandedChange: [expandedIds: string[]];
  activate: [nodeId: string];
}>();

const instanceId = ref('');
const nodeRefs = ref<Record<string, HTMLLIElement>>({});
const typeAheadBuffer = ref('');
const typeAheadTimeoutId = ref<number | null>(null);
const selectionAnchor = ref('');
const focusedIdRef = ref('');

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

// Flatten tree for navigation
const flattenTree = (
  treeNodes: TreeNodeData[],
  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;
};

const allNodes = computed(() => flattenTree(props.nodes));

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

// Expansion state (controlled or uncontrolled)
const expandedIds = computed(() => {
  if (props.expandedIds) {
    return new Set(props.expandedIds);
  }
  return internalExpandedIds.value;
});

// Selection state (controlled or uncontrolled)
const selectedIds = computed(() => {
  if (props.selectedIds) {
    return new Set(props.selectedIds);
  }
  return internalSelectedIds.value;
});

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

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

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

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

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

const containerClass = computed(() => `apg-treeview ${props.className}`.trim());

// Initialize on mount
onMounted(() => {
  instanceId.value = `treeview-${Math.random().toString(36).slice(2, 11)}`;

  // Initialize expansion
  internalExpandedIds.value = new Set(props.defaultExpandedIds);

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

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

const setNodeRef = (id: string, el: HTMLLIElement | null) => {
  if (el) {
    nodeRefs.value[id] = el;
  } else {
    delete nodeRefs.value[id];
  }
};

const updateExpandedIds = (newExpandedIds: Set<string>) => {
  if (!props.expandedIds) {
    internalExpandedIds.value = newExpandedIds;
  }
  emit('expandedChange', [...newExpandedIds]);
};

const updateSelectedIds = (newSelectedIds: Set<string>) => {
  if (!props.selectedIds) {
    internalSelectedIds.value = newSelectedIds;
  }
  emit('selectionChange', [...newSelectedIds]);
};

// Synchronous focus state update (for roving tabindex)
const setFocusedId = (nodeId: string) => {
  focusedIdRef.value = nodeId;
  focusedId.value = nodeId;
};

// Deferred DOM focus (after Vue re-render)
const applyDomFocus = async (nodeId: string) => {
  await nextTick();
  nodeRefs.value[nodeId]?.focus();
};

const focusNode = (nodeId: string) => {
  setFocusedId(nodeId);
  applyDomFocus(nodeId);
};

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  for (let i = 0; i < visibleNodes.value.length; i++) {
    const index = (startIndex + i) % visibleNodes.value.length;
    const flatNode = visibleNodes.value[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 (props.multiselectable) {
        selectionAnchor.value = flatNode.node.id;
      }
      // Type-ahead only moves focus, does not change selection
      break;
    }
  }

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

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

  focusNode(nodeId);

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

  // Select and activate
  if (props.multiselectable) {
    selectNode(nodeId);
    selectionAnchor.value = nodeId;
  } else {
    updateSelectedIds(new Set([nodeId]));
  }
  emit('activate', nodeId);
};

const handleNodeFocus = (nodeId: string) => {
  focusedIdRef.value = nodeId;
  focusedId.value = nodeId;
};

// Determine if key should be handled and call preventDefault synchronously
const shouldHandleKey = (key: string, ctrlKey: boolean, metaKey: boolean): boolean => {
  const handledKeys = [
    'ArrowDown',
    'ArrowUp',
    'ArrowRight',
    'ArrowLeft',
    'Home',
    'End',
    'Enter',
    ' ',
    '*',
  ];
  if (handledKeys.includes(key)) return true;
  // Type-ahead: single printable character without ctrl/meta
  if (key.length === 1 && !ctrlKey && !metaKey) return true;
  // Ctrl+A in multiselect
  if ((key === 'a' || key === 'A') && (ctrlKey || metaKey) && props.multiselectable) return true;
  return false;
};

const handleKeyDown = (event: KeyboardEvent) => {
  if (visibleNodes.value.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.value;
  const currentIndex = visibleIndexMap.value.get(actualFocusedId) ?? 0;
  const currentFlatNode = visibleNodes.value[currentIndex];

  switch (key) {
    case 'ArrowDown': {
      if (currentIndex < visibleNodes.value.length - 1) {
        const nextIndex = currentIndex + 1;
        focusByIndex(nextIndex);
        const nextNode = visibleNodes.value[nextIndex];
        if (props.multiselectable && shiftKey) {
          selectRange(selectionAnchor.value, nextNode.node.id);
        } else if (props.multiselectable) {
          selectionAnchor.value = 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.value[prevIndex];
        if (props.multiselectable && shiftKey) {
          selectRange(selectionAnchor.value, prevNode.node.id);
        } else if (props.multiselectable) {
          selectionAnchor.value = 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.value.has(actualFocusedId)) {
          expandNode(actualFocusedId);
        } else {
          const nextIndex = currentIndex + 1;
          if (nextIndex < visibleNodes.value.length) {
            const nextNode = visibleNodes.value[nextIndex];
            if (nextNode.parentId === actualFocusedId) {
              focusByIndex(nextIndex);
              // Update anchor on lateral navigation in multiselect
              if (props.multiselectable) {
                selectionAnchor.value = nextNode.node.id;
              }
              // Single-select: focus moves but selection does not change
            }
          }
        }
      }
      break;
    }

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

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

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

    case 'End': {
      const lastIndex = visibleNodes.value.length - 1;
      focusByIndex(lastIndex);
      const lastNode = visibleNodes.value[lastIndex];
      if (props.multiselectable && shiftKey) {
        selectRange(selectionAnchor.value, lastNode.node.id);
      } else if (props.multiselectable) {
        selectionAnchor.value = 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 (props.multiselectable) {
          selectNode(actualFocusedId);
          selectionAnchor.value = actualFocusedId;
        } else {
          updateSelectedIds(new Set([actualFocusedId]));
        }
        // Fire activation callback
        emit('activate', actualFocusedId);
      }
      break;
    }

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

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

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

    default: {
      if (key.length === 1 && !ctrlKey && !metaKey) {
        handleTypeAhead(key);
      }
    }
  }
};
</script>
TreeNode.vue 
<template>
  <li
    :ref="(el) => emit('setRef', node.id, el as HTMLLIElement | null)"
    role="treeitem"
    :aria-labelledby="labelId"
    :aria-expanded="hasChildren ? isExpanded : undefined"
    :aria-selected="isSelected"
    :aria-disabled="node.disabled || undefined"
    :tabindex="isFocused ? 0 : -1"
    :class="nodeClass"
    :style="{ '--depth': depth }"
    @click.stop="handleClick"
    @focus="handleFocus"
  >
    <span class="apg-treeview-item-content">
      <span v-if="hasChildren" class="apg-treeview-item-icon" aria-hidden="true">
        {{ isExpanded ? '\u25BC' : '\u25B6' }}
      </span>
      <span :id="labelId" class="apg-treeview-item-label">
        {{ node.label }}
      </span>
    </span>
    <ul v-if="hasChildren && isExpanded && node.children" role="group" class="apg-treeview-group">
      <TreeNode
        v-for="child in node.children"
        :key="child.id"
        :node="child"
        :depth="depth + 1"
        :instance-id="instanceId"
        :expanded-ids="expandedIds"
        :selected-ids="selectedIds"
        :focused-id="focusedId"
        :visible-index-map="visibleIndexMap"
        @node-click="(id: string) => emit('nodeClick', id)"
        @node-focus="(id: string) => emit('nodeFocus', id)"
        @set-ref="(id: string, el: HTMLLIElement | null) => emit('setRef', id, el)"
      />
    </ul>
  </li>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import type { TreeNodeData } from './TreeView.vue';

interface TreeNodeProps {
  node: TreeNodeData;
  depth: number;
  instanceId: string;
  expandedIds: Set<string>;
  selectedIds: Set<string>;
  focusedId: string;
  visibleIndexMap: Map<string, number>;
}

const props = defineProps<TreeNodeProps>();

const emit = defineEmits<{
  nodeClick: [nodeId: string];
  nodeFocus: [nodeId: string];
  setRef: [id: string, el: HTMLLIElement | null];
}>();

const hasChildren = computed(() => Boolean(props.node.children && props.node.children.length > 0));
const isExpanded = computed(() => props.expandedIds.has(props.node.id));
const isSelected = computed(() => props.selectedIds.has(props.node.id));
const isFocused = computed(() => props.focusedId === props.node.id);

const labelId = computed(() => `${props.instanceId}-label-${props.node.id}`);

const nodeClass = computed(() => {
  const classes = ['apg-treeview-item'];
  if (isSelected.value) {
    classes.push('apg-treeview-item--selected');
  }
  if (props.node.disabled) {
    classes.push('apg-treeview-item--disabled');
  }
  if (hasChildren.value) {
    classes.push('apg-treeview-item--parent');
  } else {
    classes.push('apg-treeview-item--leaf');
  }
  return classes.join(' ');
});

const handleClick = () => {
  emit('nodeClick', props.node.id);
};

const handleFocus = (e: FocusEvent) => {
  // Only handle focus if this element is the actual target (not bubbled from child)
  if (e.target === e.currentTarget) {
    emit('nodeFocus', props.node.id);
  }
};
</script>

Usage

Example 
<script setup>
import TreeView from './TreeView.vue';

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

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

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

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

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

  <!-- With default expanded -->
  <TreeView
    :nodes="nodes"
    aria-label="Files"
    :default-expanded-ids="['documents']"
  />

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

  <!-- With callbacks -->
  <TreeView
    :nodes="nodes"
    aria-label="Files"
    @selection-change="handleSelectionChange"
    @expanded-change="handleExpandedChange"
    @activate="handleActivate"
  />
</template>

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 Payload Description
@selection-change string[] Emitted when selection changes
@expanded-change string[] Emitted when expansion state changes
@activate string Emitted 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

Resources