Tree

When to useLink to "When to use"

• Nested data where the hierarchy matters: a file system, a document outline, an inspector.

Use something else when:

• there is only one level: a list or a Menu
• sections of content open and close: Accordion

UsageLink to "Usage"

import { Tree } from "@arshad-shah/cynosure";

<Tree label="Files" items={files} defaultExpanded={["src"]} onSelectionChange={([id]) => openFile(id)} />

Selection and expansion work controlled (selected, expanded) or uncontrolled (defaultSelected, defaultExpanded).

Children on demandLink to "Children on demand"

Give an item hasChildren and no children, and pass loadChildren. The first time it opens, a loading row shows, then the children. If loading fails, a row says so and retries with Enter or a click.

Very large treesLink to "Very large trees"

With virtual, only the rows in view are in the page, so a document with 100,000 visible rows stays fast. Give the tree a height; all rows must share one height. The focused row always stays mounted, so the keyboard keeps working after scrolling.

Custom rowsLink to "Custom rows"

renderLabel replaces the row text, for a value next to a key, a badge or a count. Type-ahead still matches the plain label.

A schema explorerLink to "A schema explorer"

Groups (kind: "group") head the rows under them: Enter, Space and a click open and close them, they are never selected, and they end with their child count. Items take an icon colour (iconTone, iconColor), a trailing count or badge, your own data (handed back in every callback), actions (buttons at the row's end) and a contextMenu. A pressed action or a chosen command calls onCommand(value, item).

<Tree<Table>
  label="Schema"
  items={[{ id: "tables", label: "Tables", kind: "group", children: tables.map((t) => ({
    id: t.name, label: t.name, icon: table, iconTone: "accent", trailing: format(t.rows), data: t,
    actions: [{ value: "view", label: "View data", icon: rows }],
    contextMenu: [{ value: "view", label: "View data" }, { value: "copy", label: "Copy name" }],
  })) }]}
  onCommand={(command, item) => run(command, item.data)}
/>

Actions show while their row is hovered, focused or selected, and always on screens without hover. On the focused row they come right after it in the Tab order: Tab reaches them, Shift+Tab or Escape goes back to the row, and the arrows still move between rows. The tree keys stay those of the APG pattern and the tree keeps a single way in; every action can also be in the context menu, which Shift+F10 opens.

FilteringLink to "Filtering"

filter shows only matching items, with their ancestors opened and their own children, and marks the matched text with HighlightedText. A string matches anywhere in the label, ignoring case. A function returns true, false, or the positions a fuzzy matcher found, which are marked exactly. The expanded ids are not changed, and an opened ancestor can still be closed. Only known children are searched.

Loading from a storeLink to "Loading from a store"

When children are fetched somewhere else (a store), put them in children when they arrive and say what is happening with loadingIds and errorIds. onRetry is called when a failed item is retried; renderError(item, retry) and renderEmpty(item) draw the error row and the row under an open item with no children. With loadChildren, the handle's reload(id) loads an item's children again.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Roles: role="tree" (with aria-multiselectable in multiple mode) and treeitem rows with aria-level, aria-posinset, aria-setsize, aria-expanded, aria-selected (not on groups), aria-busy while children load and aria-keyshortcuts="Shift+F10" with a context menu. A row with actions is named by its label and trailing text.
• Context menu: one ContextMenu beside the tree, not inside it (a tree holds only tree items); focus returns to the row.
• Focus: one Tab stop; the focused row is the only row in the Tab order, followed by its action buttons.
• Direction: in right-to-left text, Left and Right swap, and closed chevrons point left.
• Performance: only expanded branches are rendered, and rows are memoised, so moving focus re-renders two rows even in a tree of thousands.

TouchLink to "Touch"

Rows are at least 44px tall on coarse pointers. Row actions always show on screens without hover, with 44px hit areas, and a long press opens a row's context menu.

ThemingLink to "Theming"

Tokens: --cy-tree-indent, --cy-tree-row-height, --cy-tree-selected-bg, --cy-tree-group-ink (group rows) and --cy-tree-trailing-ink (trailing text; on a selected row it takes the row's colour).

createTheme({ components: { tree: { indent: "20px", rowHeight: "28px" } } });

RelatedLink to "Related"

HighlightedText · ContextMenu · Accordion · Menu · Combobox