HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
TreeView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA hierarchy of items, with branches that open and close.StableSince 0.1.0NavigationUsageimport'@fusion.dev/helix/tree'import'@fusion.dev/helix-headless/tree'Preview
API ReferenceRoothelix-treeA hierarchy of items, with branches that open and close.
PropTypeDescriptionactivestringThe value of the current item.canceledLabelstringDefault"Canceled"What screen readers hear when a held item is put back, or a move is
refused, in a reorderable tree.chevronPlacement"start"|"end"Which end of the row the branch chevron sits at.defaultActivestringDefault""The value of the item declared current in markup.droppedLabelstringDefault"Dropped"What screen readers hear when a held item is dropped, in a reorderable tree.emptyTextstringDefault"Nothing to show"The text shown and announced when there are no rows and none are loading.labelstringDefault"Tree"Accessible name for the tree.loadingbooleanDefaultfalseWhether the rows are still loading.loadingTextstringDefault"Loading"The text shown and announced while the rows load.movedIntoLabelstringDefault"{name} moved into {parent}, position {position} of {count}"What screen readers hear when an item moves into another branch, in a
reorderable tree. {name} is the item's words, {parent} the words of
the branch it moved into, or the tree's label for the top level,
{position} its place there, counting from 1, and {count} the number of
items there.movedLabelstringDefault"{name} moved to position {position} of {count}"What screen readers hear each time an item moves, in a reorderable
tree. {name} is the item's words, {position} its place among its
siblings, counting from 1, and {count} the number of siblings.nesting"heading"|"peer"|"subordinate"What a deeper level means: peer for no change, subordinate for a lower
rank, or heading for a parent that heads the items under it.pickedUpLabelstringDefault"Picked up {name}"What screen readers hear when a click on a grip picks up an item, in a
reorderable tree. {name} is the item's words.reorderablebooleanDefaultfalseLets you move items among their siblings, by dragging a grip or with Alt
and an arrow. The tree moves no item itself: you move your data on
helix-reorder.selectionMode"leaf"|"multiple"Whether a reader can check many items, or choose only the items at the
ends. Unset, one item is chosen at a time, branches included.valuesstring[]The checked values, as a list, under selection-mode="multiple", and the
chosen value alone otherwise. Writing it sets active.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The tree's items.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the current node changes, so the tree already holds the new one.helix-before-activateHelixBeforeActivateEventFired before the current node changes, and cancelable. Canceling it is the only way to stop the change.helix-before-reorderHelixBeforeReorderEventFired when an item is dropped at a new place among its siblings, in a reorderable tree, with the siblings' keys in the new order. Cancelable: cancel it to keep the item where it is.helix-reorderHelixReorderEventFired after helix-before-reorder when nobody canceled it. Move your items to the order in keys, each an item's value, or its words where it has none. Cancelable: cancel it to say the move did not happen.helix-selectHelixSelectEventFired when an item is chosen. The item sends it, and you can listen for it on the tree. Cancelable: canceling it changes nothing.
MethodTypeDescriptionrequestActive(next: string, cause: string) => booleanRequests a new current item, and returns whether the change was applied.
PartDescriptiondrag-previewA copy of the row a pointer drags by its grip, which follows the pointer in the top layer until the item is let go, in a reorderable tree. Hidden from assistive technology.emptyShown when there are no rows to show.liveA copy of the empty and loading messages, and each step of a move in a reorderable tree, in a live region that announces them when they change. Visually hidden in the styled tier.loadingShown while the rows load.treeThe tree container.
CSS PropertyDescription--tree-chevron-gapThe space before the chevron. Set from chevron-placement.--tree-chevron-orderThe chevron's order in the row. Set from chevron-placement and read by each item.--tree-chevron-sizeSize of the chevron, and the gutter a leaf reserves.--tree-drag-preview-background-colorThe fill behind the copy of an item a pointer drags.--tree-drag-preview-border-colorThe color of the edge around the copy of an item a pointer drags.--tree-drag-preview-border-widthThe width of the edge around the copy of an item a pointer drags. None by default, where the shadow lifts it.--tree-drag-preview-opacityThe opacity of the copy of an item a pointer drags.--tree-drag-preview-radiusThe corner radius of the copy of an item a pointer drags.--tree-drag-preview-shadowThe shadow that raises the copy of an item a pointer drags over the page.--tree-gapSpace between rows.--tree-indentIndent added per level.--tree-row-sizeMinimum height of a row, so rows with and without an icon match.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Itemhelix-tree-itemOne node in a tree.
PropTypeDescriptiondefaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.disabledbooleanDefaultfalseWhether the item cannot be chosen, opened or followed. The arrow keys still
reach it, so a reader knows it is there.focusablebooleanDefaultfalseWhether this item holds the tree's single tab stop.hrefstringDefault""The URL this node links to. Setting it makes the row a link.lazybooleanDefaultfalseWhether the item is a branch whose children are loaded when it opens.levelnumberThe node's depth from the root. The tree counts it, so indentation needs no
nested CSS.openbooleanWhether the element is open.relstringDefault""The link's rel value, which describes how the linked page relates to this
one.selectedbooleanDefaultfalseWhether this item is the current one.targetstringDefault""Where the link opens. Use it for a row that leaves the site.valuestringDefault""Identifies the item to your code. It is sent in helix-select.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The item's label. A nested item does not go here: give it slot="children". In a development build, an item nested here is reported.chevronReplaces the expand and collapse mark of a branch. A slotted icon is sized and turned like the drawn one.childrenNested items, which make this a branch.endContent after the label, at the far side of the row, such as a count or a state.startContent before the label and after the chevron, such as a mark for the item.
EventTypeDescriptionhelix-before-closeHelixBeforeCloseEventFired before a branch closes, and cancelable.helix-before-openHelixBeforeOpenEventFired before a branch opens, and cancelable.helix-loadHelixLoadEventFired when a lazy item opens, so you can load its children.helix-selectHelixSelectEventFired when the item is chosen, and cancelable. Canceling it changes nothing.toggleToggleEventSent when the branch opens or closes, with newState and oldState.
MethodTypeDescriptionactivate() => voidChooses this node, as a press or Enter does.focusItem() => voidMoves focus to this node.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.select() => voidSelects this node and sends helix-select. A disabled node sends nothing.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptioncheckboxThe check mark's box, in a tree with selection-mode="multiple".checkbox-checkedThe check mark's box while the item is checked.checkbox-mixedThe check mark's box while some of a branch's items are checked.gripThe handle a pointer drags to move the item, in a reorderable tree.grip-markThe icon on the grip.groupThe container for nested items.itemThe node, and the focus target.labelThe label text.rowThe clickable label row.toggleThe expand and collapse control.
CSS PropertyDescription--tree-checkbox-background-colorFill of the check mark's box.--tree-checkbox-border-colorBorder of the check mark's box.--tree-checkbox-mark-colorColor of the check, and of the bar of a partly checked branch.--tree-checkbox-sizeSize of the check mark's box. Follows the chevron's size.--tree-chevron-sizeSize of the chevron, and the gutter a leaf reserves.--tree-dragging-opacityThe opacity of an item being moved, in a reorderable tree.--tree-drop-indicator-colorThe color of the line where a moved item would land.--tree-drop-indicator-sizeThe thickness of the line where a moved item would land.--tree-gapSpace between rows.--tree-grip-colorThe color of the grip, in a reorderable tree.--tree-indentIndent added per level.--tree-levelHow deep this row sits, counting from one as aria-level does, for the indent.--tree-row-checked-background-colorFill of a checked row, in a tree with selection-mode="multiple". Unset, the box alone marks it.--tree-row-checked-colorText color of a checked row, in a tree with selection-mode="multiple".--tree-row-colorText color of a row at rest.--tree-row-disabled-opacityHow faint a disabled row is drawn.--tree-row-hover-background-colorFill of a row under the pointer.--tree-row-hover-colorText color of a row under the pointer.--tree-row-radiusCorners of a row's fill.--tree-row-selected-background-colorFill of the chosen row, in a tree of one choice.--tree-row-selected-colorText color of the chosen row, in a tree of one choice.--tree-row-sizeMinimum height of a row, so rows with and without an icon match.
Custom stateDescriptioncheckedWhile it is checked, in a tree with selection-mode="multiple".draggingThe item is being moved, in a reorderable tree.drop-afterThe item being moved goes after this one when it is dropped.drop-beforeThe item being moved goes before this one when it is dropped.loadingWhile a lazy item is open and its children have not arrived.mixedWhile some of a branch's items are checked, in a tree with selection-mode="multiple".openWhile its children are shown.selectedWhile it is selected.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-treeA hierarchy of items, with branches that open and close.
PropTypeDescriptionactivestringThe value of the current item.canceledLabelstringDefault"Canceled"What screen readers hear when a held item is put back, or a move is
refused, in a reorderable tree.defaultActivestringDefault""The value of the item declared current in markup.droppedLabelstringDefault"Dropped"What screen readers hear when a held item is dropped, in a reorderable tree.emptyTextstringDefault"Nothing to show"The text shown and announced when there are no rows and none are loading.labelstringDefault"Tree"Accessible name for the tree.loadingbooleanDefaultfalseWhether the rows are still loading.loadingTextstringDefault"Loading"The text shown and announced while the rows load.movedIntoLabelstringDefault"{name} moved into {parent}, position {position} of {count}"What screen readers hear when an item moves into another branch, in a
reorderable tree. {name} is the item's words, {parent} the words of
the branch it moved into, or the tree's label for the top level,
{position} its place there, counting from 1, and {count} the number of
items there.movedLabelstringDefault"{name} moved to position {position} of {count}"What screen readers hear each time an item moves, in a reorderable
tree. {name} is the item's words, {position} its place among its
siblings, counting from 1, and {count} the number of siblings.nesting"heading"|"peer"|"subordinate"What a deeper level means: peer for no change, subordinate for a lower
rank, or heading for a parent that heads the items under it.pickedUpLabelstringDefault"Picked up {name}"What screen readers hear when a click on a grip picks up an item, in a
reorderable tree. {name} is the item's words.reorderablebooleanDefaultfalseLets you move items among their siblings, by dragging a grip or with Alt
and an arrow. The tree moves no item itself: you move your data on
helix-reorder.selectionMode"leaf"|"multiple"Whether a reader can check many items, or choose only the items at the
ends. Unset, one item is chosen at a time, branches included.valuesstring[]The checked values, as a list, under selection-mode="multiple", and the
chosen value alone otherwise. Writing it sets active.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The tree's items.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the current node changes, so the tree already holds the new one.helix-before-activateHelixBeforeActivateEventFired before the current node changes, and cancelable. Canceling it is the only way to stop the change.helix-before-reorderHelixBeforeReorderEventFired when an item is dropped at a new place among its siblings, in a reorderable tree, with the siblings' keys in the new order. Cancelable: cancel it to keep the item where it is.helix-reorderHelixReorderEventFired after helix-before-reorder when nobody canceled it. Move your items to the order in keys, each an item's value, or its words where it has none. Cancelable: cancel it to say the move did not happen.helix-selectHelixSelectEventFired when an item is chosen. The item sends it, and you can listen for it on the tree. Cancelable: canceling it changes nothing.
MethodTypeDescriptionrequestActive(next: string, cause: string) => booleanRequests a new current item, and returns whether the change was applied.
PartDescriptiondrag-previewA copy of the row a pointer drags by its grip, which follows the pointer in the top layer until the item is let go, in a reorderable tree. Hidden from assistive technology.emptyShown when there are no rows to show.liveA copy of the empty and loading messages, and each step of a move in a reorderable tree, in a live region that announces them when they change. Visually hidden in the styled tier.loadingShown while the rows load.treeThe tree container.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Itemhelix-headless-tree-itemOne node in a tree.
PropTypeDescriptiondefaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.disabledbooleanDefaultfalseWhether the item cannot be chosen, opened or followed. The arrow keys still
reach it, so a reader knows it is there.focusablebooleanDefaultfalseWhether this item holds the tree's single tab stop.hrefstringDefault""The URL this node links to. Setting it makes the row a link.lazybooleanDefaultfalseWhether the item is a branch whose children are loaded when it opens.levelnumberThe node's depth from the root. The tree counts it, so indentation needs no
nested CSS.openbooleanWhether the element is open.relstringDefault""The link's rel value, which describes how the linked page relates to this
one.selectedbooleanDefaultfalseWhether this item is the current one.targetstringDefault""Where the link opens. Use it for a row that leaves the site.valuestringDefault""Identifies the item to your code. It is sent in helix-select.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The item's label. A nested item does not go here: give it slot="children". In a development build, an item nested here is reported.chevronReplaces the expand and collapse mark of a branch, such as with your own icon.childrenNested items, which make this a branch.endContent after the label, at the far side of the row, such as a count or a state.startContent before the label and after the chevron, such as a mark for the item.
EventTypeDescriptionhelix-before-closeHelixBeforeCloseEventFired before a branch closes, and cancelable.helix-before-openHelixBeforeOpenEventFired before a branch opens, and cancelable.helix-loadHelixLoadEventFired when a lazy item opens, so you can load its children.helix-selectHelixSelectEventFired when the item is chosen, and cancelable. Canceling it changes nothing.toggleToggleEventSent when the branch opens or closes, with newState and oldState.
MethodTypeDescriptionactivate() => voidChooses this node, as a press or Enter does.focusItem() => voidMoves focus to this node.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.select() => voidSelects this node and sends helix-select. A disabled node sends nothing.toggleOpen() => booleanOpens or closes a branch, unless the item is disabled.
PartDescriptioncheckboxThe check mark's box, in a tree with selection-mode="multiple".checkbox-checkedThe check mark's box while the item is checked.checkbox-mixedThe check mark's box while some of a branch's items are checked.gripThe handle a pointer drags to move the item, in a reorderable tree. Hidden from screen readers, which move the item with Alt and an arrow.grip-markThe icon on the grip.groupThe container for nested items.itemThe node, and the focus target unless href moves it to the row.labelThe label text.rowThe clickable label row, which is an <a> where href is set.toggleThe expand and collapse control.
CSS PropertyDescription--tree-levelHow deep this row sits, counting from one as aria-level does, for the indent.
Custom stateDescriptioncheckedWhile it is checked, in a tree with selection-mode="multiple".draggingThe item is being moved, in a reorderable tree.drop-afterThe item being moved goes after this one when it is dropped.drop-beforeThe item being moved goes before this one when it is dropped.loadingWhile a lazy item is open and its children have not arrived.mixedWhile some of a branch's items are checked, in a tree with selection-mode="multiple".openWhile its children are shown.selectedWhile it is selected.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionChevron PlacementThe branch chevron at each end of the row.ControlledA tree whose current node is set by your code, as a router needs.Eventshelix-select bubbles to the tree and the open and close events do not, so each has its own listener.MultipleA tree of check marks, where checking a folder checks everything in it.NestingDepth as a position, depth as a rank, and a branch that is a heading.NestingDepth as a position, depth as a rank, and a branch that is a heading.PreviewNested nodes that open and close, with one marked current.PreviewNested nodes that open and close, with one marked current.ReorderingItems you move among their siblings by dragging a grip, or with Alt and an arrow key.With IconsA tree with a folder icon in the start slot of each branch.