Tree selection

Problem Context

• The choices are naturally hierarchical, such as folders, permissions, taxonomy categories, organization units, product groups, or nested settings.
• Users need to expand and collapse branches to control detail while preserving selected nodes.
• Selecting a parent may imply selecting descendants, selecting only the parent, or showing a mixed state; the product must define that rule.
• Users may need to select several nodes while exploring the hierarchy without accidental selection changes.
• The hierarchy can be large enough to require typeahead, lazy loading, selected-count summaries, or dynamic position metadata.

Selection Rules

• Choose tree selection when hierarchy is meaningful to the user's selection task and the parent-child relationship changes how options are found or interpreted.
• Use listbox when options are flat and users only need a visible selectable list without branch expansion.
• Use checkbox group when the option set is short, flat, and independent enough for native checkboxes.
• Use transfer list when users need to move selected items into a separate destination pane for review or ordering.
• Use tree grid when rows need columns, editable cells, row actions, sorting, or tabular comparison.
• Use navigation tree only when selecting a node changes page location rather than choosing values for a form or operation.
• Use aria-selected or aria-checked consistently; choose checkbox-style visual treatment when branch and mixed state are central.
• Avoid tree selection when hierarchy is used only to compress a long flat list; use search, grouping, filters, or autocomplete instead.

Required States

• Initial tree state with visible label and root-level nodes.
• Expanded parent node with visible child group.
• Collapsed parent node with hidden child group.
• Focused active treeitem state distinct from selected state.
• Selected leaf node state.
• Unselected selectable node state.
• Mixed or partially selected parent state.
• Selected collapsed branch summary state.
• Nonselectable branch or leaf state.
• Single-select and multi-select policy states.
• Typeahead matched node state.
• Lazy-loading branch state with loading feedback and eventual level and position metadata.
• Required empty-tree-selection validation state with selected branches and collapsed descendants preserved.

Interaction Contract

• The tree container has role tree and a visible label referenced by aria-labelledby or an accessible name.
• Each selectable node has role treeitem and exposes selected state with either aria-selected or aria-checked, used consistently across the tree.
• Parent nodes that own children expose aria-expanded true or false; leaf nodes do not expose aria-expanded.
• Child collections are grouped with role group or an equivalent owned treeitem relationship.
• In multi-select trees, the tree exposes aria-multiselectable and focus movement does not alter selection unless the user explicitly toggles selection.
• Right Arrow opens a closed parent or moves from an open parent to its first child; Left Arrow closes an open parent or moves focus to the parent from a child.
• Up and Down Arrow move through visible treeitems only; hidden collapsed descendants are not reachable.
• Space toggles the focused selectable node, and branch selection rules update child and parent mixed states predictably.
• Typeahead moves focus to the next visible matching node without changing selection.
• Collapsed branches with selected descendants remain visibly marked so users do not lose track of hidden selections.

Implementation Checklist

• Confirm that hierarchy is essential to selection rather than presentation grouping or navigation.
• Define whether users can select branches, leaves only, multiple nodes, ranges, or entire subtrees.
• Choose either aria-selected or aria-checked for selectable treeitems and keep visual state aligned with the accessibility tree.
• Implement role tree, role treeitem, group nesting, accessible labels, aria-expanded only on parents, and aria-multiselectable when multiple nodes can be selected.
• Implement roving tabindex or aria-activedescendant, visible focus, Arrow-key expansion and movement, Home, End, typeahead, Space selection, and optional range selection.
• Show selected-descendant state on collapsed parents and mixed state when a branch has only some selected descendants.
• Preserve selected nodes during collapse, filtering, async loading, validation, route changes, and save errors.
• For dynamically loaded or virtualized trees, maintain aria-level, aria-setsize, aria-posinset, loading status, and stable active descendant IDs.
• Test keyboard, screen reader, high zoom, forced colors, long labels, deep nesting, collapsed selected branches, branch selection, leaf-only policy, and touch fallback.

Common Generated-UI Mistakes

• Using tree selection for a flat list where listbox, checkbox group, or multi-select would be simpler.
• Styling nested checkboxes as a tree without tree keyboard behavior or expanded state.
• Letting focus movement change multi-selection while users are only exploring nodes.
• Putting aria-expanded on leaf nodes.
• Mixing aria-selected and aria-checked with the same meaning in one tree.
• Hiding selected children inside collapsed branches with no parent summary or mixed state.
• Using tree selection for ordinary site navigation or menu commands.
• Putting independent buttons, menus, or editable fields inside treeitems instead of using a tree grid or adjacent actions.

Critique Questions

• Is the hierarchy meaningful to the selection decision, or is this a flat list with indentation?
• Can users tell which row has focus versus which nodes are selected?
• What happens when users select a parent branch: descendants selected, branch only, mixed, or blocked?
• Are selected descendants still visible through parent state after a branch collapses?
• Can keyboard users expand, collapse, move, typeahead, select, and validate without tabbing through every node?