Skip to content
Kimenpre-v1documentation home
Color scheme

ki-tree

Use a tree for file browsers, nested categories, or an outline that people need to explore branch by branch. Use a list for a flat collection. Name the tree with label and put the item’s text before its nested ki-tree-item children.

Theme for this example
Color scheme for this example
src ki-dialog.ts ki-menu.ts README.md
<ki-tree label="Project files">
<ki-tree-item expanded>
src
<ki-tree-item selected>ki-dialog.ts</ki-tree-item>
<ki-tree-item>ki-menu.ts</ki-tree-item>
</ki-tree-item>
<ki-tree-item>README.md</ki-tree-item>
</ki-tree>

Multiple selection

Set selection="multiple" to show checkboxes. Checking a branch selects its enabled descendants. A branch appears mixed when only some of its enabled descendants are selected. The ki-selection-change event carries the selected items in detail.selectedItems.

Theme for this example
Color scheme for this example
Reports Summary Appendix Draft
<ki-tree label="Export files" selection="multiple">
<ki-tree-item expanded>
Reports
<ki-tree-item selected>Summary</ki-tree-item>
<ki-tree-item>Appendix</ki-tree-item>
<ki-tree-item disabled>Draft</ki-tree-item>
</ki-tree-item>
</ki-tree>

For navigation, set selection="none" and give destinations an href. Listen for ki-expand and ki-collapse to observe disclosure changes. A lazy branch emits ki-load on first expansion. Append the returned child items to event.detail.item. If the request finishes with no items, set lazy to false to stop the spinner. Use loading-label to name the activity in the document language.

Keyboard

Tab moves into and out of the tree as one stop. Up and Down move among visible items. Use the arrow toward the children to expand a branch or move to its first child, and the opposite arrow to collapse it or return to its parent. The arrows follow the reading direction. Home and End move to the ends of the visible tree. Type the beginning of an item name to reach it directly. Space selects or checks an item. Enter follows the destination on a link.

API reference

When to use: browse nested files, categories or an outline, select items in a hierarchy, or navigate through linked destinations.

When not to use: flat lists of peers, menus of commands, or submitted form values.

Properties & attributes

AttributePropertyTypeDefaultDescription
labellabelstring'Tree'Accessible name of the hierarchy. Localize it and make it distinct among nearby trees.
selectionselection"multiple" | "none" | "single"'single'Use none for navigation, single for one selected item, or multiple for checkable branches.

Events

EventDetail typeDescription
ki-selection-changeCustomEvent<{ selectedItems: HTMLKiTreeItemElement[] }>Emitted after a user selection changes. Selected items are in tree order.

Slots

SlotDescription
(default)Direct ki-tree-item children in reading order.

CSS parts

PartDescription
baseThe surface around the hierarchy.

CSS custom properties

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

TokenDescription
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-tree-backdrop-filterComplete backdrop filter behind the surface.
--ki-tree-bgBase surface of the hierarchy.
--ki-tree-bg-imageOptional image layered over the tree surface.
--ki-tree-edgePerimeter color of the hierarchy surface.
--ki-tree-edge-widthWidth of the surface and checkbox outlines.
--ki-tree-fgText on the base surface.
--ki-tree-paddingInterior padding of the hierarchy surface.
--ki-tree-radiusRounding of the hierarchy surface.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-size-body-1semantic dimension for typography size body 1.

Workshop

Open Tree in Storybook