Tree API

Component status:: stable

Import

import { Tree } from "@stratakit/structures";
// OR
import * as Tree from "@stratakit/structures/Tree";

Tree.Root

Base element: <div>

A tree is a hierarchical list of items that can be expanded or collapsed, or optionally selected.

Tree.Root is the root component for a tree. Tree.Items are rendered as a flat list in the Tree.Root component to create a hierarchical tree structure.

Example:

<Tree.Root>
  <Tree.Item label="Parent 1" aria-level={1} aria-posinset={1} aria-setsize={2} />
  <Tree.Item label="Child 1.1" aria-level={2} aria-posinset={1} aria-setsize={2} />
  <Tree.Item label="Child 1.2" aria-level={2} aria-posinset={2} aria-setsize={2} />
  <Tree.Item label="Parent 2" aria-level={1} aria-posinset={2} aria-setsize={2} />
  <Tree.Item label="Child 2.1" aria-level={2} aria-posinset={1} aria-setsize={1} />
</Tree.Root>

Additional props

render

Tree.Item

Base element: <div>

A treeitem is a node in a tree structure that may be expanded or collapsed to reveal or hide its descendants.

Tree.Items can be rendered inside a Tree.Root. Additional properties are specified to the Tree.Items to create a hierarchical tree structure.

Example:

<Tree.Root>
  <Tree.Item label="Parent" aria-level={1} aria-posinset={1} aria-setsize={1} />
  <Tree.Item label="Child 1" aria-level={2} aria-posinset={1} aria-setsize={2} />
  <Tree.Item label="Child 2" aria-level={2} aria-posinset={2} aria-setsize={2}  />
</Tree.Root>

The label and icon props can be used to specify the treeitem’s own content.

The aria-level prop is used to specify the nesting level of the treeitem. Nesting levels start at 1.

The aria-posinset and aria-setsize props are used to define the treeitem’s position in the current level of tree items.

The expanded and onExpandedChange props can be used to control the expansion state of a treeitem.

The selected and onSelectedChange props can be used to control the selection state of a treeitem.

Secondary actions can be passed into the actions prop.

aria-level

Type: number (required)

Specifies the nesting level of the tree item. Nesting levels start at 1.

aria-posinset

Type: number (required)

Defines tree item position in the current level of tree items. Integer greater than or equal to 1.

aria-setsize

Type: number (required)

Defines tree item set size of the current level.

actions

Type: ReactNode[] | undefined (optional)

The secondary actions available for the tree item displayed in a dropdown menu. Must be a list of Tree.ItemAction components.

actions={[
  <Tree.ItemAction key={…} icon={…} label={…} />,
  <Tree.ItemAction key={…} icon={…} label={…} />,
]}

description

Type: ReactNode (optional)

Secondary line of text to display additional information about the tree item.

error

Type: string | boolean | undefined (optional)

Default: false

Specifies if the tree item is in an error state. The id for an associated error message (e.g. <ErrorRegion.Item>) can be passed as a string.

Can be combined with the actions prop to display an error-related action (e.g. “Retry”). The first action will be made visible by default.

expanded

Type: boolean | undefined (optional)

Default: undefined

Specifies if the tree item is expanded.

Used to determine if a tree item is a parent node. If undefined, it is a leaf node (i.e. not expandable).

icon

Type: string | Element | undefined (optional)

Icon to be displayed inside the tree item.

Can be a URL of an SVG from the @stratakit/icons package, or a JSX element.

For multiple icons/decorations, use the unstable_decorations prop.

inlineActions

Type: ReactNode[] | undefined (optional)

The secondary actions available for the tree item displayed as icon buttons in a toolbar. Must be a list of Tree.ItemAction components.

Example:

inlineActions={
  error
    ? [
        <Tree.ItemAction key={…} icon={…} label={…} />
      ]
    : [
        <Tree.ItemAction key={…} icon={…} label={…} />,
        <Tree.ItemAction key={…} icon={…} label={…} />,
      ]
}

Inline actions should only be used for frequently used and quickly accessible actions. At most two inline actions are displayed. A single action should be specified when tree item has an error.

The inline actions are normally hidden until the treeitem is hovered or focused. When the error prop is set, the actions will be made visible by default. The first action slot should usually be used to display an error-related action.

label

Type: ReactNode (optional)

The primary label that identifies the tree item and is displayed inside it.

onExpandedChange

Type: ((expanded: boolean) => void) | undefined (optional)

Callback fired when the tree item is expanded.

Should be used with the expanded prop.

onSelectedChange

Type: ((selected: boolean) => void) | undefined (optional)

Callback fired when the tree item is selected.

Should be used with the selected prop.

render

Type: (props: P) => React.ReactNode | React.ReactElement | undefined (optional)

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

selected

Type: boolean | undefined (optional)

Default: undefined

Specifies if the tree item is selected.

If undefined, the tree item is not selectable.

unstable_decorations

Type: ReactNode (optional)

Decoration(s) to be displayed inside the tree item.

This is an alternative to the icon prop, and can be used to display multiple icons or other decorations before the label.

Note: This should not be used together with the icon prop.

Tree.ItemAction

Base element: <button>

A secondary action for <Tree.Item>, to be passed into the actions prop. The action is typically displayed as an icon-button or a menu-item (e.g. when overflowing).

By default, the action appears only when the treeitem has hover/focus or an error. This behavior can be overridden using the visible prop.

label

Type: string (required)

Label for the action.

Will be displayed as a tooltip when the action is an icon-button, otherwise will be displayed as a label inside the menu-item.

dot

Type: string | undefined (optional)

A small dot displayed in the corner of the action.

The value of this prop gets used as the button’s “accessible description”.

Example:

<Tree.ItemAction
  label="Filter"
  dot="Some filters applied"
  icon={…}
/>

icon

Type: string | Element | undefined (optional)

Icon for the action.

Can be a URL of an SVG from the @stratakit/icons package, or a JSX element.

Required when the action is displayed as an icon-button (i.e. not overflowing).

render

Type: (props: P) => React.ReactNode | React.ReactElement | undefined (optional)

Check out the Composition guide for more details.

visible

Type: boolean | undefined (optional)

Controls the visibility of the action (only when the action is displayed as icon-button).

If true, the action is always visible. If false, the action is hidden and becomes inaccessible, but still occupies space.

By default, the action is shown only when the treeitem receives hover/focus. When the treeitem has an error, the action will become always visible (i.e. it will default to true when error is set).