TreeView

Single-select hierarchy with branch expansion and keyboard navigation.

Overview

  • Use a tree for nested collections that users expand and navigate by depth.

Aliases

tree

When to use

  • Use TreeView for nested resources that users expand in place.
  • Use descriptions sparingly to support ambiguous nodes without overwhelming the tree.

When not to use

  • Do not use TreeView when the structure is effectively flat.
  • Do not use TreeView for drag-and-drop, typeahead-heavy, or multi-select trees.

Structural parts

tree row

item

Single hierarchical row with level, selection, and branch state.

expand and collapse control

branch

Opens or closes a node with children.

supporting node text

description

Optional secondary copy beneath the main label.

Public interface

Props
NameTypeDefaultDescription
itemsArray<{ id: string; label: string; description?: string; disabled?: boolean; children?: TreeViewItem[] }>—Tree definitions with nested child arrays.
valuestring—Controlled selected node ID.
expandedIdsstring[]—Controlled expanded branch IDs.
onChange(detail: { value: string | undefined }) => void—Runs when the selected node changes.
onExpandedChange(detail: { ids: string[] }) => void—Runs when the expanded branch set changes.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
change{ value: string | undefined }Fires when the component commits a new value.
expandedchange{ ids: string[] }Fires when expanded branches change.
Slots
NameDescription
defaultTreeView is data-driven and does not expose node slots.

Variants, sizes, and states

Variants

  • default: Single-select hierarchical tree with depth indentation.

Sizes

  • default: TreeView uses one density tuned for readable hierarchy.

States

  • collapsed: Branch closed
  • expanded: Branch open
  • selected: Current node selected

Accessibility

Semantics

  • Uses tree and treeitem semantics with explicit level and expanded state.

Keyboard

  • Arrow keys move, expand, collapse, and return to parent nodes. Home and End jump to the first and last visible rows.

Screen readers

  • Depth, branch state, and selection remain understandable through the tree semantics.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-tree-gap
0.25rem

item

--dk-tree-item-bg
#f2f5fb
--dk-tree-item-fg
#16181c
--dk-tree-item-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-tree-item-min-height
44px
--dk-tree-item-inline-padding
0.625rem

label

--dk-tree-label-size
0.92rem
--dk-tree-label-weight
600

description

--dk-tree-description-fg
#16181c
--dk-tree-description-size
0.75rem

branch

--dk-tree-branch-size
0.85rem

Implementation notes

  • TreeView supports one selected item.

Examples

Starter

Nested resource list

A readable hierarchical list with one expanded branch.

<TreeView items={treeItems} expandedIds={['workspace']} value="overview" />

Common patterns

Ambiguous nodes with descriptions

Descriptions can clarify similarly named nodes without changing the structure.

<TreeView items={[{ id: 'workspace', label: 'Workspace', children: [{ id: 'activity', label: 'Activity', description: 'Recent events' }] }]} expandedIds={['workspace']} />

Edge cases

Externally controlled branches

Control selection and expanded branches when app state owns the hierarchy.

<TreeView items={treeItems} value={selectedNode} expandedIds={expanded} onChange={(detail) => selectedNode = detail.value} onExpandedChange={(detail) => expanded = detail.ids} />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

default

pass

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, layout
  • Evaluated: contrast, target, layout
  • Contrast: 98.5 Lc
  • Target: 44 px
  • Layout: root · single-line 0 px single-line estimate; 0 px minimum width
    240 px: pass 320 px: pass

selected

pass

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, layout
  • Evaluated: contrast, target, layout
  • Contrast: 89.9 Lc
  • Target: 44 px
  • Layout: root · single-line 0 px single-line estimate; 0 px minimum width
    240 px: pass 320 px: pass