Skip to content
Kimenpre-v1documentation home
Color scheme

ki-tree-item

Use a tree item inside Tree or another tree item. A row contains its text label and any nested child items. Set expanded to start with its children visible. A disabled row remains reachable with the arrow keys.

Import the glyph module before using its name in icon-name. The label text names the row and the icon is decorative.

import '@kimen/elements/icons/file-code';

API reference

When to use: label a file, category or destination in a hierarchy. Nest more ki-tree-item children for a branch.

When not to use: standalone controls, form checkboxes, or a row with other interactive descendants.

Properties & attributes

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalseKeep the row discoverable by keyboard while preventing user activation.
expandedexpandedbooleanfalseWhether a branch reveals its children. Has no visible effect on a leaf.
hrefhrefstring | undefined–Native destination of the row. Prefer selection="none" for navigation trees.
icon-nameiconNamestring | undefined–Optional decorative icon. Import the named Kimen glyph before mounting the tree.
lazylazybooleanfalseRequest children on the first empty expansion. Clear it to finish an empty load.
loading-labelloadingLabelstring'Loading'Localized text for the spinner status during an outstanding lazy request.
selectedselectedbooleanfalseSelected state. The tree keeps it in sync with single selection or fully checked branches.

Events

EventDetail typeDescription
ki-collapseCustomEvent<{ item: HTMLKiTreeItemElement }>Emitted when an existing branch collapses.
ki-expandCustomEvent<{ item: HTMLKiTreeItemElement }>Emitted when an existing branch expands.
ki-loadCustomEvent<{ item: HTMLKiTreeItemElement }>Emitted once when an empty lazy branch first opens. The listener supplies the children.

Slots

SlotDescription
(default)The row label and directly nested ki-tree-item children.

CSS parts

PartDescription
checkboxCheck-state indicator and hit area in multiple selection.
disclosureLeading hit area and direction indicator of a branch.
groupThe region containing the expanded child items.
labelVisible row text or native destination link.
rowThe painted and focus-highlighted item row.

CSS custom properties

The public styling contract of ki-tree-item: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-control-offsetAdded to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min.
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-tree-disclosure-durationDisclosure turn duration.
--ki-tree-disclosure-easingDisclosure turn easing.
--ki-tree-edge-widthWidth of the surface and checkbox outlines.
--ki-tree-focus-ring-colorInk of the focused row outline.
--ki-tree-focus-ring-widthWidth of the focused row outline.
--ki-tree-hover-bgFill of an unselected row hovered by a fine pointer.
--ki-tree-hover-fgText of an unselected row hovered by a fine pointer.
--ki-tree-icon-fgDefault ink of the decorative row icons.
--ki-tree-indentInline indentation per hierarchy level.
--ki-tree-item-box-radiusRounding of the visual checkbox indicator.
--ki-tree-item-box-sizeSize of the visual checkbox indicator.
--ki-tree-item-gapSpace between an optional item icon and its label.
--ki-tree-item-paddingInline-end inset of an item row.
--ki-tree-item-radiusRounding of a highlighted item row.
--ki-tree-item-targetMinimum inline target of a disclosure or checkbox.
--ki-tree-row-heightMinimum block size before density adjustment.
--ki-tree-selected-bgFill of a selected or checked row.
--ki-tree-selected-fgText and glyph ink on a selected row.
--ki-tree-touch-row-minMinimum row block size on a coarse pointer.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.

Workshop

Open Tree item in Storybook