ki-tree
@kimen/elements/ki-tree- Source
- Agent reference
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.
<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.
<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>Navigation and lazy branches
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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
label | label | string | 'Tree' | Accessible name of the hierarchy. Localize it and make it distinct among nearby trees. |
selection | selection | "multiple" | "none" | "single" | 'single' | Use none for navigation, single for one selected item, or multiple for checkable branches. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-selection-change | CustomEvent<{ selectedItems: HTMLKiTreeItemElement[] }> | Emitted after a user selection changes. Selected items are in tree order. |
Slots
| Slot | Description |
|---|---|
| (default) | Direct ki-tree-item children in reading order. |
CSS parts
| Part | Description |
|---|---|
base | The 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.
| Token | Description |
|---|---|
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-tree-backdrop-filter | Complete backdrop filter behind the surface. |
--ki-tree-bg | Base surface of the hierarchy. |
--ki-tree-bg-image | Optional image layered over the tree surface. |
--ki-tree-edge | Perimeter color of the hierarchy surface. |
--ki-tree-edge-width | Width of the surface and checkbox outlines. |
--ki-tree-fg | Text on the base surface. |
--ki-tree-padding | Interior padding of the hierarchy surface. |
--ki-tree-radius | Rounding of the hierarchy surface. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-body-1 | semantic dimension for typography line height body 1. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |