Tree

Usage

Tree shows hierarchical data as expandable rows. One component has two semantics, picked by mode.

Data mode

A WAI-ARIA tree. Use it for content a person browses and selects: files, protocols, folders, categories.

The tree must be named with aria-label or aria-labelledby.
One row is tabbable. Tab enters the tree on the first selected enabled row, otherwise the first enabled row, and arrow keys move from there.
A click or Enter activates a row: it runs the row's onClick, then selects the row (selectionMode). A parent row with no href and no onClick also toggles. The chevron always toggles and never activates.
selectionMode is Single (default), Multiple or None.

Nested lists for site or app navigation. You provide the landmark; the tree provides the lists.

A row with href is a link through Link, so it follows the registered router. The selected row is the current page and its link carries aria-current="page".
A parent row with no href is a disclosure button. A parent row with an href keeps its link and gets a separate disclosure button named by toggleLabel and the row label.
Native Tab order applies. There is no roving focus and no tree role.
Clicking a link row selects it, so an uncontrolled tree moves its current-page wash. Control selected from your router to follow navigation you do not start.

Rows

Each item in items is plain data:

Field	Use
`id`, `label`	Required. `id` is unique across the whole tree. A label wider than its row stays on one line and fades at its end; on a hovering pointer, and while the row has keyboard focus, it slides to reveal the rest. The description keeps an ellipsis.
`description`	Secondary text below the label.
`icon`	Lead icon at 16px.
`counter`, `badge`, `status`	Accessories after the label. `status` needs a `label` that carries the meaning as text.
`action`	A trailing icon button.
`children`, `hasChildren`, `loading`	Nesting, and lazy loading.
`href`, `external`, `newTabLabel`	A destination.
`onClick`, `disabled`	Activation and the disabled state.

State

expanded and selected hold arrays of ids. Each is controlled with the prop and uncontrolled with defaultExpanded and defaultSelected. onExpandedChange and onSelectedChange receive the next ids and change details; details.cancel() keeps the current state.

Lazy children

Mark a row hasChildren and leave children out. Expanding it calls onExpand(id) once per expansion. Load the children, then pass them back through items. While they load, set loading on the row: it shows busy and a skeleton row appears in its group. Loading is not disabled.

Compact

compact shows only the top-level rows' lead icons, with each label in a Tooltip, and hides nested groups. A row with no icon is left out. Use it for a collapsed sidebar rail; set the width on the container.

Other props

guides draws a connector line beside each nested group (default on).
disabled disables every row. A tree inside a disabled fieldset is disabled the same way.
className, id and ref go to the root list.

Accessibility / Testing with Screen Readers

Tree / API and Development

On this page

Tree

Usage

Tree shows hierarchical data as expandable rows. One component has two semantics, picked by mode.

Data mode

A WAI-ARIA tree. Use it for content a person browses and selects: files, protocols, folders, categories.

The tree must be named with aria-label or aria-labelledby.
One row is tabbable. Tab enters the tree on the first selected enabled row, otherwise the first enabled row, and arrow keys move from there.
A click or Enter activates a row: it runs the row's onClick, then selects the row (selectionMode). A parent row with no href and no onClick also toggles. The chevron always toggles and never activates.
selectionMode is Single (default), Multiple or None.

Nested lists for site or app navigation. You provide the landmark; the tree provides the lists.

A row with href is a link through Link, so it follows the registered router. The selected row is the current page and its link carries aria-current="page".
A parent row with no href is a disclosure button. A parent row with an href keeps its link and gets a separate disclosure button named by toggleLabel and the row label.
Native Tab order applies. There is no roving focus and no tree role.
Clicking a link row selects it, so an uncontrolled tree moves its current-page wash. Control selected from your router to follow navigation you do not start.

Rows

Each item in items is plain data:

Field	Use
`id`, `label`	Required. `id` is unique across the whole tree. A label wider than its row stays on one line and fades at its end; on a hovering pointer, and while the row has keyboard focus, it slides to reveal the rest. The description keeps an ellipsis.
`description`	Secondary text below the label.
`icon`	Lead icon at 16px.
`counter`, `badge`, `status`	Accessories after the label. `status` needs a `label` that carries the meaning as text.
`action`	A trailing icon button.
`children`, `hasChildren`, `loading`	Nesting, and lazy loading.
`href`, `external`, `newTabLabel`	A destination.
`onClick`, `disabled`	Activation and the disabled state.

State

Lazy children

Compact

Other props

guides draws a connector line beside each nested group (default on).
disabled disables every row. A tree inside a disabled fieldset is disabled the same way.
className, id and ref go to the root list.

Accessibility / Testing with Screen Readers

Tree / API and Development

On this page