Tree

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import Tree, TreeMode, TreeSelectionMode from @prepared911/ui/tree.

Tree

Prop	Type	Default	Notes
`items`	`readonly TreeItemData[]`	required	Rows. Ids are unique across the tree.
`mode`	`TreeMode`	`Data`	`Data` is a `role="tree"`; `Navigation` is nested lists.
`selectionMode`	`TreeSelectionMode`	`Single`	Data mode only. `None`, `Single` or `Multiple`.
`aria-label`, `aria-labelledby`	`LocalizedMessage`, `string`		Required in data mode: one of the two. Optional in navigation mode.
`expanded`	`readonly string[]`		Controlled expanded ids.
`defaultExpanded`	`readonly string[]`	`[]`	Initial expanded ids.
`onExpandedChange`	`(expanded, details) => void`		`details.reason` is `trigger-press`, `item-press` or `list-navigation`. Cancelable.
`selected`	`readonly string[]`		Controlled selected ids. In navigation mode the one selected row is the current page.
`defaultSelected`	`readonly string[]`	`[]`	Initial selected ids.
`onSelectedChange`	`(selected, details) => void`		`details.reason` is `item-press`. Cancelable.
`onExpand`	`(id: string) => void`		A lazy row was expanded.
`compact`	`boolean`	`false`	Icons only, labels in Tooltips, no nested groups.
`guides`	`boolean`	`true`	Connector line beside nested groups.
`disabled`	`boolean`	`false`	Disables every row.
`toggleLabel`	`LocalizedMessage`		Name of a disclosure button that sits beside a link row.
`loadingLabel`	`LocalizedMessage`		Name of the skeleton row shown while children load.
`className`, `id`, `ref`			On the root `ul`.

The tree takes no style.

TreeItemData

Field	Type	Notes
`id`	`string`	Unique across the tree.
`label`	`LocalizedMessage \| DisplayValue`	Primary text.
`description`	`LocalizedMessage \| DisplayValue`	Secondary text; the row's accessible description.
`icon`	`Glyph`	Lead icon. Decorative.
`counter`	`number \| LocalizedMessage \| DisplayValue`	Resting small Counter.
`badge`	`{ text: LocalizedMessage; intent?: BadgeIntent }`	Small Badge.
`status`	`{ color: StatusDotColor; label: LocalizedMessage }`	StatusDot; `label` is read, not shown.
`action`	`{ glyph; label; onPress; disabled? }`	A trailing small ghost icon Button.
`children`	`readonly TreeItemData[]`	Nested rows.
`hasChildren`	`boolean`	A parent whose children are not loaded yet.
`loading`	`boolean`	Busy, with a skeleton row in the group.
`disabled`	`boolean`	Skipped by arrow keys and typeahead; cannot be selected, expanded or activated.
`onClick`	`(event) => void`	Activation. `preventDefaultBehavior()` skips the tree's own selection and expansion.
`href`, `external`, `newTabLabel`		A destination through `Link`. `external` requires `newTabLabel`.

Enums

TreeMode: Data, Navigation.
TreeSelectionMode: None, Single, Multiple.

Props

Name	Type	Default	Description
`items`	`readonly TreeItemData[]`	—	The rows. Ids must be unique across the whole tree.
`aria-label`	`LocalizedMessage`	—	Accessible name of the tree. Accessible name of the tree, when the element alone is not enough. Name of the root list, when the landmark alone is not enough.
`aria-labelledby`	`string`	—	Id of an element that also names the tree. Id of the element that names the tree. Id of an element that names the root list.
`className`	`string`	—	Classes appended to the root list.
`compact`	`boolean`	`false`	Shows only the top-level rows' lead icons, with each label in a Tooltip, and hides nested groups. A parent row stays as an icon and cannot expand. A row with no icon is left out.
`defaultExpanded`	`readonly string[]`	`[]`	Ids of the rows expanded at first when `expanded` is not passed.
`defaultSelected`	`readonly string[]`	`[]`	Ids of the rows selected at first when `selected` is not passed.
`disabled`	`boolean`	`false`	Disables every row: none can be focused, selected, expanded or activated. A tree inside a disabled `fieldset` is disabled the same way.
`expanded`	`readonly string[]`	—	Controlled ids of the expanded rows.
`guides`	`boolean`	`true`	Draws a connector line beside each nested group.
`id`	`string`	—	Id of the root list.
`loadingLabel`	`LocalizedMessage`	—	Accessible name of the skeleton row shown while a row's children load.
`mode`	`TreeMode`	—	`role="tree"` semantics. Default. Nested lists with disclosure buttons and links.
`onExpand`	`((id: string) => void)`	—	Called with a row's id when the row is expanded, is marked `hasChildren`, and has no `children` yet. Load the children and pass them back through `items`. It runs once per expansion, whether the change came from the user or from `expanded`.
`onExpandedChange`	`TreeExpandedChangeHandler`	—	Fires when a row asks to expand or collapse.
`onSelectedChange`	`TreeSelectedChangeHandler`	—	Fires when a row asks to be selected.
`ref`	`Ref<HTMLUListElement>`	—	Ref to the root `ul`.
`selected`	`readonly string[]`	—	Controlled ids of the selected rows. In navigation mode the one selected row is the current page.
`selectionMode`	`TreeSelectionMode`	`TreeSelectionMode.Single`	How many rows can be selected.
`toggleLabel`	`LocalizedMessage`	—	Accessible name of a disclosure control that is separate from its row, such as the toggle beside a link row in navigation mode. The row's label follows it, so the button reads, for example, "Toggle Reports".

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

On this page

Tree

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import Tree, TreeMode, TreeSelectionMode from @prepared911/ui/tree.

Tree

Prop	Type	Default	Notes
`items`	`readonly TreeItemData[]`	required	Rows. Ids are unique across the tree.
`mode`	`TreeMode`	`Data`	`Data` is a `role="tree"`; `Navigation` is nested lists.
`selectionMode`	`TreeSelectionMode`	`Single`	Data mode only. `None`, `Single` or `Multiple`.
`aria-label`, `aria-labelledby`	`LocalizedMessage`, `string`		Required in data mode: one of the two. Optional in navigation mode.
`expanded`	`readonly string[]`		Controlled expanded ids.
`defaultExpanded`	`readonly string[]`	`[]`	Initial expanded ids.
`onExpandedChange`	`(expanded, details) => void`		`details.reason` is `trigger-press`, `item-press` or `list-navigation`. Cancelable.
`selected`	`readonly string[]`		Controlled selected ids. In navigation mode the one selected row is the current page.
`defaultSelected`	`readonly string[]`	`[]`	Initial selected ids.
`onSelectedChange`	`(selected, details) => void`		`details.reason` is `item-press`. Cancelable.
`onExpand`	`(id: string) => void`		A lazy row was expanded.
`compact`	`boolean`	`false`	Icons only, labels in Tooltips, no nested groups.
`guides`	`boolean`	`true`	Connector line beside nested groups.
`disabled`	`boolean`	`false`	Disables every row.
`toggleLabel`	`LocalizedMessage`		Name of a disclosure button that sits beside a link row.
`loadingLabel`	`LocalizedMessage`		Name of the skeleton row shown while children load.
`className`, `id`, `ref`			On the root `ul`.

The tree takes no style.

TreeItemData

Field	Type	Notes
`id`	`string`	Unique across the tree.
`label`	`LocalizedMessage \| DisplayValue`	Primary text.
`description`	`LocalizedMessage \| DisplayValue`	Secondary text; the row's accessible description.
`icon`	`Glyph`	Lead icon. Decorative.
`counter`	`number \| LocalizedMessage \| DisplayValue`	Resting small Counter.
`badge`	`{ text: LocalizedMessage; intent?: BadgeIntent }`	Small Badge.
`status`	`{ color: StatusDotColor; label: LocalizedMessage }`	StatusDot; `label` is read, not shown.
`action`	`{ glyph; label; onPress; disabled? }`	A trailing small ghost icon Button.
`children`	`readonly TreeItemData[]`	Nested rows.
`hasChildren`	`boolean`	A parent whose children are not loaded yet.
`loading`	`boolean`	Busy, with a skeleton row in the group.
`disabled`	`boolean`	Skipped by arrow keys and typeahead; cannot be selected, expanded or activated.
`onClick`	`(event) => void`	Activation. `preventDefaultBehavior()` skips the tree's own selection and expansion.
`href`, `external`, `newTabLabel`		A destination through `Link`. `external` requires `newTabLabel`.

Enums

TreeMode: Data, Navigation.
TreeSelectionMode: None, Single, Multiple.

Props

Name	Type	Default	Description
`items`	`readonly TreeItemData[]`	—	The rows. Ids must be unique across the whole tree.
`aria-label`	`LocalizedMessage`	—	Accessible name of the tree. Accessible name of the tree, when the element alone is not enough. Name of the root list, when the landmark alone is not enough.
`aria-labelledby`	`string`	—	Id of an element that also names the tree. Id of the element that names the tree. Id of an element that names the root list.
`className`	`string`	—	Classes appended to the root list.
`compact`	`boolean`	`false`	Shows only the top-level rows' lead icons, with each label in a Tooltip, and hides nested groups. A parent row stays as an icon and cannot expand. A row with no icon is left out.
`defaultExpanded`	`readonly string[]`	`[]`	Ids of the rows expanded at first when `expanded` is not passed.
`defaultSelected`	`readonly string[]`	`[]`	Ids of the rows selected at first when `selected` is not passed.
`disabled`	`boolean`	`false`	Disables every row: none can be focused, selected, expanded or activated. A tree inside a disabled `fieldset` is disabled the same way.
`expanded`	`readonly string[]`	—	Controlled ids of the expanded rows.
`guides`	`boolean`	`true`	Draws a connector line beside each nested group.
`id`	`string`	—	Id of the root list.
`loadingLabel`	`LocalizedMessage`	—	Accessible name of the skeleton row shown while a row's children load.
`mode`	`TreeMode`	—	`role="tree"` semantics. Default. Nested lists with disclosure buttons and links.
`onExpand`	`((id: string) => void)`	—	Called with a row's id when the row is expanded, is marked `hasChildren`, and has no `children` yet. Load the children and pass them back through `items`. It runs once per expansion, whether the change came from the user or from `expanded`.
`onExpandedChange`	`TreeExpandedChangeHandler`	—	Fires when a row asks to expand or collapse.
`onSelectedChange`	`TreeSelectedChangeHandler`	—	Fires when a row asks to be selected.
`ref`	`Ref<HTMLUListElement>`	—	Ref to the root `ul`.
`selected`	`readonly string[]`	—	Controlled ids of the selected rows. In navigation mode the one selected row is the current page.
`selectionMode`	`TreeSelectionMode`	`TreeSelectionMode.Single`	How many rows can be selected.
`toggleLabel`	`LocalizedMessage`	—	Accessible name of a disclosure control that is separate from its row, such as the toggle beside a link row in navigation mode. The row's label follows it, so the button reads, for example, "Toggle Reports".

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

On this page