GGamma

Design catalogue

Source atlas

Components9 results

ComponentsNavigation

Tree navigator

Explore and select a nested hierarchy with guide lines, independent disclosure, and complete keyboard navigation.

Open in Gamma

What to study

  • Tab enters one tree item. Up/Down move through visible enabled rows; Home/End reach the first or last row. Typing a label prefix moves focus.
  • Right opens a branch or enters its children; Left closes it or returns to its parent. These directions mirror in RTL. Enter and Space select the focused row.
  • Click a row to select it, or its chevron to expand without selecting. Selection does not follow focus, and opening a branch preserves selection.
  • Disabled items and their descendants are skipped by arrow navigation. If a focused branch collapses or a focused node disappears, focus returns to its nearest available ancestor.
  • Only open children are mounted. This component is synchronous, single-select, and unvirtualized; owners supply updated node data and handle navigation in onValueChange.
  • Only disclosure rotation animates; reduced motion removes transitions. All interactive colors, shapes, typography, focus, and motion use Gamma design-system tokens.
  • Icon and meta slots should contain noninteractive content. Stable unique IDs are required for selection, expansion, focus, and React keys.

Topics

References

Material

Status
New
Source File
src/components/TreeNavigator.tsx
Design System
gamma
Props
  • Name
    nodes
    Type
    readonly TreeNavigatorNode[]
    Default
    —
    Description
    The node hierarchy. Every ID must be unique and stable across the tree.
  • Name
    label
    Type
    string
    Default
    Navigation
    Description
    Accessible tree name; aria-label or aria-labelledby can override it.
  • Name
    value / defaultValue
    Type
    string | null
    Default
    null
    Description
    Controlled or initial single selected ID. Selection is separate from expansion.
  • Name
    onValueChange
    Type
    (id: string, node: TreeNavigatorNode) => void
    Default
    —
    Description
    Runs when a row is activated by pointer, Enter, or Space, including reactivation.
  • Name
    expandedIds / defaultExpandedIds
    Type
    readonly string[]
    Default
    []
    Description
    Controlled or initial open branch IDs. Closed descendants are unmounted.
  • Name
    onExpandedChange
    Type
    (ids: string[]) => void
    Default
    —
    Description
    Receives branch expansion changes from disclosure buttons and arrow keys.
  • Name
    showLines
    Type
    boolean
    Default
    true
    Description
    Connects nested levels with token-colored guide lines.
  • Name
    size
    Type
    "default" | "compact"
    Default
    default
    Description
    Chooses standard or compact row density; touch devices retain larger targets.
  • Name
    disabled
    Type
    boolean
    Default
    false
    Description
    Disables every item while preserving the hierarchy for reading.
  • Name
    emptyState
    Type
    ReactNode
    Default
    No items to display.
    Description
    Content shown when the node array is empty.
  • Name
    className / native list attributes
    Type
    HTMLAttributes<HTMLUListElement>
    Default
    —
    Description
    Pass-through attributes for the root tree, including style and accessible naming.
  • Name
    TreeNavigatorNode
    Type
    { id; label; children?; icon?; meta?; disabled? }
    Default
    —
    Description
    Node data; icon is decorative, meta is noninteractive supporting content, and disabled applies to descendants.