TreeView

TreeView is a hierarchical list of items that may have a parent-child relationship where children can be toggled into view by expanding or collapsing their parent item.

Page navigation navigation

React

readyReviewed for a11y

Storybook|Source

Figma

View in Figma|

React examples

Default

Parent node
- Child node one
- Child node two
Sibling node one
Sibling node two

<TreeView aria-label="Files changed">
  <TreeView.Item id="parent-node-one" defaultExpanded>
    Parent node
    <TreeView.SubTree>
      <TreeView.Item id="child-node-one">Child node one</TreeView.Item>
      <TreeView.Item id="child-node-two" current>
        Child node two
      </TreeView.Item>
    </TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="sibling-node-one">Sibling node one</TreeView.Item>
  <TreeView.Item id="sibling-node-two">Sibling node two</TreeView.Item>
</TreeView>

<TreeView aria-label="Files changed">
  <TreeView.Item id="parent-node-one" defaultExpanded>
    Parent node
    <TreeView.SubTree>
      <TreeView.Item id="child-node-one">Child node one</TreeView.Item>
      <TreeView.Item id="child-node-two" current>
        Child node two
      </TreeView.Item>
    </TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="sibling-node-one">Sibling node one</TreeView.Item>
  <TreeView.Item id="sibling-node-two">Sibling node two</TreeView.Item>
</TreeView>

Nodes with leading visuals and trailing visuals

Leading and trailing visual guidelines

src
- Avatar.tsx
- Button.tsx
package.json

<TreeView aria-label="Files changed">
  <TreeView.Item id="src" defaultExpanded>
    <TreeView.LeadingVisual>
      <TreeView.DirectoryIcon />
    </TreeView.LeadingVisual>
    src
    <TreeView.SubTree>
      <TreeView.Item id="src/Avatar.tsx">
        <TreeView.LeadingVisual>
          <FileIcon />
        </TreeView.LeadingVisual>
        Avatar.tsx
        <TreeView.TrailingVisual label="Added">
          <DiffAddedIcon fill="var(--fgColor-success)" />
        </TreeView.TrailingVisual>
      </TreeView.Item>
      <TreeView.Item id="src/Button.tsx" current>
        <TreeView.LeadingVisual>
          <FileIcon />
        </TreeView.LeadingVisual>
        Button.tsx
        <TreeView.TrailingVisual label="Modified">
          <DiffModifiedIcon fill="var(--fgColor-attention)" />
        </TreeView.TrailingVisual>
      </TreeView.Item>
    </TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="package.json">
    <TreeView.LeadingVisual>
      <FileIcon />
    </TreeView.LeadingVisual>
    package.json
    <TreeView.TrailingVisual label="Modified">
      <DiffModifiedIcon fill="var(--fgColor-attention)" />
    </TreeView.TrailingVisual>
  </TreeView.Item>
</TreeView>

<TreeView aria-label="Files changed">
  <TreeView.Item id="src" defaultExpanded>
    <TreeView.LeadingVisual>
      <TreeView.DirectoryIcon />
    </TreeView.LeadingVisual>
    src
    <TreeView.SubTree>
      <TreeView.Item id="src/Avatar.tsx">
        <TreeView.LeadingVisual>
          <FileIcon />
        </TreeView.LeadingVisual>
        Avatar.tsx
        <TreeView.TrailingVisual label="Added">
          <DiffAddedIcon fill="var(--fgColor-success)" />
        </TreeView.TrailingVisual>
      </TreeView.Item>
      <TreeView.Item id="src/Button.tsx" current>
        <TreeView.LeadingVisual>
          <FileIcon />
        </TreeView.LeadingVisual>
        Button.tsx
        <TreeView.TrailingVisual label="Modified">
          <DiffModifiedIcon fill="var(--fgColor-attention)" />
        </TreeView.TrailingVisual>
      </TreeView.Item>
    </TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="package.json">
    <TreeView.LeadingVisual>
      <FileIcon />
    </TreeView.LeadingVisual>
    package.json
    <TreeView.TrailingVisual label="Modified">
      <DiffModifiedIcon fill="var(--fgColor-attention)" />
    </TreeView.TrailingVisual>
  </TreeView.Item>
</TreeView>

Nodes with leading actions

Item 1
Item 2
Item 3

<TreeView aria-label="Issues">
  <TreeView.Item id="item-0">
    <TreeView.LeadingAction>
      <IconButton icon={GrabberIcon} aria-label="Reorder item 1" variant="invisible" />
    </TreeView.LeadingAction>
    <TreeView.LeadingVisual label="Issue closed">
      <IssueClosedIcon fill="var(--fgColor-done)" />
    </TreeView.LeadingVisual>
    Item 1
  </TreeView.Item>
  <TreeView.Item id="item-2">
    <TreeView.LeadingAction>
      <IconButton icon={GrabberIcon} aria-label="Reorder item 2" variant="invisible" />
    </TreeView.LeadingAction>
    <TreeView.LeadingVisual label="Issue opened">
      <IssueOpenedIcon fill="var(--fgColor-open)" />
    </TreeView.LeadingVisual>
    Item 2
    <TreeView.SubTree>
      <TreeView.Item id="item-2-sub-task-1">
        <TreeView.LeadingVisual label="Issue opened">
          <IssueOpenedIcon fill="var(--fgColor-open)" />
        </TreeView.LeadingVisual>
        sub task 1
      </TreeView.Item>
      <TreeView.Item id="item-2-sub-task-2">
        <TreeView.LeadingVisual label="Issue opened">
          <IssueOpenedIcon fill="var(--fgColor-open)" />
        </TreeView.LeadingVisual>
        sub task 2
      </TreeView.Item>
    </TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="item-3">
    <TreeView.LeadingAction>
      <IconButton icon={GrabberIcon} aria-label="Reorder item 3" variant="invisible" />
    </TreeView.LeadingAction>
    <TreeView.LeadingVisual label="Issue opened">
      <IssueOpenedIcon fill="var(--fgColor-open)" />
    </TreeView.LeadingVisual>
    Item 3
  </TreeView.Item>
</TreeView>

<TreeView aria-label="Issues">
  <TreeView.Item id="item-0">
    <TreeView.LeadingAction>
      <IconButton icon={GrabberIcon} aria-label="Reorder item 1" variant="invisible" />
    </TreeView.LeadingAction>
    <TreeView.LeadingVisual label="Issue closed">
      <IssueClosedIcon fill="var(--fgColor-done)" />
    </TreeView.LeadingVisual>
    Item 1
  </TreeView.Item>
  <TreeView.Item id="item-2">
    <TreeView.LeadingAction>
      <IconButton icon={GrabberIcon} aria-label="Reorder item 2" variant="invisible" />
    </TreeView.LeadingAction>
    <TreeView.LeadingVisual label="Issue opened">
      <IssueOpenedIcon fill="var(--fgColor-open)" />
    </TreeView.LeadingVisual>
    Item 2
    <TreeView.SubTree>
      <TreeView.Item id="item-2-sub-task-1">
        <TreeView.LeadingVisual label="Issue opened">
          <IssueOpenedIcon fill="var(--fgColor-open)" />
        </TreeView.LeadingVisual>
        sub task 1
      </TreeView.Item>
      <TreeView.Item id="item-2-sub-task-2">
        <TreeView.LeadingVisual label="Issue opened">
          <IssueOpenedIcon fill="var(--fgColor-open)" />
        </TreeView.LeadingVisual>
        sub task 2
      </TreeView.Item>
    </TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="item-3">
    <TreeView.LeadingAction>
      <IconButton icon={GrabberIcon} aria-label="Reorder item 3" variant="invisible" />
    </TreeView.LeadingAction>
    <TreeView.LeadingVisual label="Issue opened">
      <IssueOpenedIcon fill="var(--fgColor-open)" />
    </TreeView.LeadingVisual>
    Item 3
  </TreeView.Item>
</TreeView>

Without indentation

Parent node
- Child node one
- Child node two
Sibling node one
Sibling node two

<TreeView flat aria-label="Files changed">
  <TreeView.Item id="parent-node-one" defaultExpanded>
    Parent node
    <TreeView.SubTree>
      <TreeView.Item id="child-node-one">Child node one</TreeView.Item>
      <TreeView.Item id="child-node-two" current>
        Child node two
      </TreeView.Item>
    </TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="sibling-node-one">Sibling node one</TreeView.Item>
  <TreeView.Item id="sibling-node-two">Sibling node two</TreeView.Item>
</TreeView>

<TreeView flat aria-label="Files changed">
  <TreeView.Item id="parent-node-one" defaultExpanded>
    Parent node
    <TreeView.SubTree>
      <TreeView.Item id="child-node-one">Child node one</TreeView.Item>
      <TreeView.Item id="child-node-two" current>
        Child node two
      </TreeView.Item>
    </TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="sibling-node-one">Sibling node one</TreeView.Item>
  <TreeView.Item id="sibling-node-two">Sibling node two</TreeView.Item>
</TreeView>

Loading subtree - child node count known

When we know the number of loading child nodes, show "skeleton" nodes until the nodes finish loading. This reassures the user that their request is in progress and provides a minimal preview of what's loading.

Parent node
- Loading 2 items
Sibling node one
Sibling node two

<TreeView aria-label="Files changed">
  <TreeView.Item id="parent-node-one" defaultExpanded>
    Parent node
    <TreeView.SubTree state="loading" count={2}></TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="sibling-node-one">Sibling node one</TreeView.Item>
  <TreeView.Item id="sibling-node-two">Sibling node two</TreeView.Item>
</TreeView>

<TreeView aria-label="Files changed">
  <TreeView.Item id="parent-node-one" defaultExpanded>
    Parent node
    <TreeView.SubTree state="loading" count={2}></TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="sibling-node-one">Sibling node one</TreeView.Item>
  <TreeView.Item id="sibling-node-two">Sibling node two</TreeView.Item>
</TreeView>

Loading subtree - child node count unknown

When we don't know the number of loading child nodes, show a generic loading indicator.

Parent node
- Loading...
Sibling node one
Sibling node two

<TreeView aria-label="Files changed">
  <TreeView.Item id="parent-node-one" defaultExpanded>
    Parent node
    <TreeView.SubTree state="loading"></TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="sibling-node-one">Sibling node one</TreeView.Item>
  <TreeView.Item id="sibling-node-two">Sibling node two</TreeView.Item>
</TreeView>

<TreeView aria-label="Files changed">
  <TreeView.Item id="parent-node-one" defaultExpanded>
    Parent node
    <TreeView.SubTree state="loading"></TreeView.SubTree>
  </TreeView.Item>
  <TreeView.Item id="sibling-node-one">Sibling node one</TreeView.Item>
  <TreeView.Item id="sibling-node-two">Sibling node two</TreeView.Item>
</TreeView>

More code examples

The previous examples are a curated subset of the full capabilities of the TreeView component. For more examples, see the TreeView Storybook stories.

Props

TreeView

Name	Required	Description
aria-label		`string`
aria-labelledby		`string`
className		`string` Class name(s) used to customize styles
flat		`boolean` Prevents the tree from indenting items. This should only be used when the tree is used to display a flat list of items.
truncate		`boolean` Whether to truncate node text
children	Required	`React.ReactNode`

TreeView.Item

Name	Required	Description
children	Required	`React.ReactNode`
id	Required	`string` A unique identifier for the item.
aria-label		`string`
aria-labelledby		`string`
className		`string` Class name(s) used to customize styles
current		`boolean` Indicates whether the item is the current item. No more than one item should be current at once. The path to the current item will be expanded by default.
defaultExpanded		`boolean` The expanded state of the item when it is initially rendered. Use when you do not need to control the state.
expanded		`boolean` The controlled expanded state of item. Must be used in conjunction with onExpandedChange.
containIntrinsicSize		`string` The size of this item's contents. Passing this will set 'content-visiblity: auto' on the content container, delaying rendering until the item is in the viewport.
onExpandedChange		`(expanded: boolean) => void` Event handler called when the expanded state of the item changes.
onSelect		`(event: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>) => void`
truncate		`boolean` Truncate the item's text content with an ellipsis.
ref		`React.Ref<HTMLElement>`

TreeView.LeadingVisual

Name	Required	Description
children	Required	`\| React.ReactNode \| (props: {isExpanded: boolean}) => React.ReactNode)`
label		`string` Provide an accessible label for the visual. This is not necessary for decorative visuals.

TreeView.TrailingVisual

Name	Required	Description
children	Required	`\| React.ReactNode \| (props: {isExpanded: boolean}) => React.ReactNode)`
label		`string` Provide an accessible label for the visual. This is not necessary for decorative visuals.

TreeView.DirectoryIcon

Name	Required	Description

TreeView.SubTree

Name	Required	Description
children		`React.ReactNode`
state		`\| 'initial' \| 'loading' \| 'done' \| 'error'` Specify a state if items in the subtree are loaded asynchronously. An asynchronous subtree can be in one of the following states: 'initial', 'loading', 'done', or 'error'. In the 'initial' state, items are neither loaded nor loading. In the 'loading' state, items are loading and the subtree will render a loading indicator. In the 'done' state, items are loaded. Screen readers will announce when a subtree enters the 'done' state. An 'error' state means that an error occured while loading items.
count		`number` The number of items expected to be in the subtree. When in the loading state, the subtree will render a skeleton loading placeholder with the specified count of items
aria-label		`string` An accessible name for the subtree. It is recommended that you provide a short version of the parent list item's name as the name of the subtree.

TreeView.ErrorDialog

Name	Required	Description
children	Required	`React.ReactNode` The content of the dialog. This is usually a message explaining the error.
title		`string` The title of the dialog. This is usually a short description of the error.
onRetry		`() => void` Event handler called when the user clicks the retry button.
onDismiss		`() => void` Event handler called when the dialog is dismissed.