Tree Navigation
Note
A component that organizes content into vertically stacked collapsible and expandable sections.
Design checklist
| Status | Item | Description |
|---|---|---|
| ✔️ | Anatomy | Includes descriptions of all parts of the component and its major variants. |
| ✔️ | States | Includes all applicable interaction, display and value states. |
| ✔️ | Options | Includes all relevant options (functional type, stylistic kind, semantic color, size, orientation, optional iconography, decorations, etc.) |
| ✔️ | Color schemes | Includes both light and dark color schemes. |
| Behaviors | Includes descriptions of behaviors related to other components and responsive behaviors related to media breakpoints, size (minimums and maximums), orientation, alignment, position and layout (wrapping, truncation, overflow). |
Anatomy
- Tree container: The outer wrapper for the navigation tree structure.
- Tree node: Individual item in the tree, which may represent a folder, file, or section.
- Expand/collapse icon: Icon or indicator to expand or collapse child nodes.
- Node label: The visible text or content for each node.
- Node icon (optional): Icon representing the type of node (e.g., folder, file).
- Children: Nested nodes representing the hierarchical structure.
- Action buttons (optional): Buttons for actions like add, remove, or rename nodes.
States
- Default: Standard appearance, nodes are collapsed or expanded as set.
- Expanded: Node is expanded to show its children.
- Collapsed: Node is collapsed, hiding its children.
- Selected: Node is highlighted to indicate selection.
- Focused: Node is focused for keyboard navigation.
- Disabled: Node is non-interactive and visually muted.
- Loading: Node is loading its children (if lazy loading is supported).
- Error: Node failed to load children (if applicable).
Options
- data: Tree data structure representing nodes and hierarchy.
- selectedNode: Currently selected node.
- onSelect: Callback when a node is selected.
- onExpand/collapse: Callbacks for expanding or collapsing nodes.
- renderNode: Custom render function for nodes.
- icons: Custom icons for node types or expand/collapse.
- actions: Array of action buttons for each node.
- theme: Theme (
default,alternative). - disabled: Disable interaction for the whole tree or specific nodes.
- className: Custom class names for styling.
Behaviors
- Expand/collapse: Nodes can be expanded or collapsed to show or hide children.
- Selection: Nodes can be selected via click or keyboard.
- Keyboard navigation: Supports arrow keys, Enter, and Space for navigation and actions.
- Lazy loading: Loads children on demand (if supported).
- Custom actions: Action buttons for add, remove, rename, etc.
- Accessibility: Uses ARIA roles and attributes for tree navigation and supports screen readers.
- Disabled: Prevents interaction for disabled nodes or the whole tree.
- Error handling: Shows error state if loading children fails.
Changelog
| Date | Type | Description | Author | Associated issue(s) |
|---|---|---|---|---|
| YYYY-MM-DD | new | Initial design | Oanh Nguyen | PAR-52 |