Tree

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Hierarchical list, navigation tree, file tree

Description: The Tree component displays a hierarchical list in which each item can contain child entries. Items with children can be collapsed or expanded to show or hide deeper levels.

Example

Standard tree with multiple levels and expandable items:

<KolTree _label="Sitemap" > <KolTreeItem _label="Home" _href="#/" _active /> <KolTreeItem _label="Page 1" _href="#/page-1" _open> <KolTreeItem _label="Page 1.1" _href="#/page-1/1" /> <KolTreeItem _label="Page 1.2" _href="#/page-1/2" /> </KolTreeItem> <KolTreeItem _label="Page 2" _href="#/page-2" /> </KolTree>

Accessibility

The Tree component is designed with accessibility and keyboard navigation in mind:

• Hierarchical navigation: The tree structure can be operated completely with the keyboard and is exposed clearly for screen reader users.
• ARIA roles and attributes: The component uses the standardized WAI-ARIA tree pattern to convey its semantic structure.
• Keyboard support: Comprehensive keyboard interaction with arrow keys, Enter, Home, and End enables efficient navigation.
• Focus management: Clear focus indication and predictable focus movement support orientation.
• Label requirement: Every tree requires a _label so its purpose is communicated to all users.

Links and references

Usage

Keyboard interaction

Key	Function
Tab	Focuses the tree so it can be operated with the keyboard.
↑ / ↓	Moves between visible items on the same level.
→	Opens the submenu of the currently focused item, if it has children.
←	Closes the submenu, if it is open, or moves focus to the parent item.
Enter	Activates the currently focused item. If _href is present, navigation occurs.
Home	Focuses the first item in the tree.
End	Focuses the last item in the tree.
*	Opens all closed sibling items on the current level.
Alphanumeric	Typing a character focuses the next item whose _label starts with that character. Repeating the same character continues to the next matching item.

Best practices

• Use the Tree component for complex hierarchical data sets with multiple nesting levels.
• Use _label on the tree to describe the overall purpose of the structure, for example site map, file system, or organization chart.
• Configure each KolTreeItem with _label, _href, and optionally _active.
• Use _open={true} on items that should be visible immediately, such as top-level branches or primary navigation points.
• Limit the initially visible depth so the structure remains easy to scan.
• Use _active only to mark the current location or selection, not as a purely decorative state.
• Keep _label values concise so the tree remains readable and responsive.

Use cases

• File and folder navigation
• Hierarchical site maps or navigation menus
• Organization or project structures
• Category trees in CMS or catalog systems
• Adaptive menus based on context or user role
• API or configuration structure browsers

FAQ

Can I lazy-load tree items?
The KoliBri tree does not provide built-in lazy loading. You can implement it at application level by inserting or removing items when a branch is expanded.

How many nesting levels are supported?
Technically, any number of levels is possible. In practice, the initially visible depth should stay limited to avoid overloading users.

Can I combine the tree with filtering?
Yes. Filtering is handled at application level by adjusting the data or rendered items passed into the tree.

Construction / Technical

Playground

Test the different properties of the tree component:

<KolTree _label="Sitemap" > <KolTreeItem _label="Home" _href="#/" _active /> <KolTreeItem _label="Page 1" _href="#/page-1" _open> <KolTreeItem _label="Page 1.1" _href="#/page-1/1" /> <KolTreeItem _label="Page 1.2" _href="#/page-1/2" /> </KolTreeItem> <KolTreeItem _label="Page 2" _href="#/page-2" /> </KolTree>

Features with code

Basic tree structure

Each node is represented by a KolTreeItem component. The container is defined by KolTree with the required _label attribute.

<KolTree _label="Sitemap" > <KolTreeItem _label="Home" _href="#/" _active /> <KolTreeItem _label="Page 1" _href="#/page-1" _open> <KolTreeItem _label="Page 1.1" _href="#/page-1/1" /> <KolTreeItem _label="Page 1.2" _href="#/page-1/2" /> </KolTreeItem> <KolTreeItem _label="Page 2" _href="#/page-2" /> </KolTree>

Expanded and collapsed states

The _open attribute on KolTreeItem controls whether an item is expanded on initial load.

<KolTree _label="Sitemap" > <KolTreeItem _label="Home" _href="#/" _active /> <KolTreeItem _label="Page 1" _href="#/page-1" _open> <KolTreeItem _label="Page 1.1" _href="#/page-1/1" /> <KolTreeItem _label="Page 1.2" _href="#/page-1/2" /> </KolTreeItem> <KolTreeItem _label="Page 2" _href="#/page-2" /> </KolTree>

Active state

The _active attribute marks a tree item as currently active, for example the current page in a navigation.

<KolTree _label="Sitemap" > <KolTreeItem _label="Home" _href="#/" _active /> <KolTreeItem _label="Page 1" _href="#/page-1" _open> <KolTreeItem _label="Page 1.1" _href="#/page-1/1" /> <KolTreeItem _label="Page 1.2" _href="#/page-1/2" /> </KolTreeItem> <KolTreeItem _label="Page 2" _href="#/page-2" /> </KolTree>

Nested hierarchies

The tree supports arbitrary nesting depths through nested KolTreeItem elements.

<KolTree _label="Sitemap" > <KolTreeItem _label="Home" _href="#/" _active /> <KolTreeItem _label="Page 1" _href="#/page-1" _open> <KolTreeItem _label="Page 1.1" _href="#/page-1/1" /> <KolTreeItem _label="Page 1.2" _href="#/page-1/2" /> </KolTreeItem> <KolTreeItem _label="Page 2" _href="#/page-2" /> </KolTree>

API

Properties

Property	Attribute	Description	Type	Default
_label (required)	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).	string	undefined

Methods

focus

focus() => Promise<void>

Sets focus on the first focusable tree item.

Returns

Type: Promise<void>

---