TreeView

A hierarchical list of items where nested items can be expanded and collapsed.

Draft
Review pending by accessibility team

On this page

Examples

<Box sx={{maxWidth: 400}}>
  <nav aria-label="File navigation">
    <TreeView aria-label="File navigation">
      <TreeView.Item>
        <TreeView.LeadingVisual>
          <TreeView.DirectoryIcon />
        </TreeView.LeadingVisual>
        src
        <TreeView.SubTree>
          <TreeView.LinkItem href="#">
            <TreeView.LeadingVisual>
              <FileIcon />
            </TreeView.LeadingVisual>
            Avatar.tsx
            <TreeView.TrailingVisual>
              <StyledOcticon icon={DiffAddedIcon} color="success.fg" aria-label="added" />
            </TreeView.TrailingVisual>
          </TreeView.LinkItem>
          <TreeView.LinkItem href="#" current>
            <TreeView.LeadingVisual>
              <FileIcon />
            </TreeView.LeadingVisual>
            Button.tsx
            <TreeView.TrailingVisual>
              <StyledOcticon icon={DiffModifiedIcon} color="attention.fg" aria-label="modified" />
            </TreeView.TrailingVisual>
          </TreeView.LinkItem>
        </TreeView.SubTree>
      </TreeView.Item>
      <TreeView.LinkItem href="#">
        <TreeView.LeadingVisual>
          <FileIcon />
        </TreeView.LeadingVisual>
        package.json
        <TreeView.TrailingVisual>
          <StyledOcticon icon={DiffModifiedIcon} color="attention.fg" aria-label="modified" />
        </TreeView.TrailingVisual>
      </TreeView.LinkItem>
    </TreeView>
  </nav>
</Box>

<Box sx={{maxWidth: 400}}>
  <nav aria-label="File navigation">
    <TreeView aria-label="File navigation">
      <TreeView.Item>
        <TreeView.LeadingVisual>
          <TreeView.DirectoryIcon />
        </TreeView.LeadingVisual>
        src
        <TreeView.SubTree>
          <TreeView.LinkItem href="#">
            <TreeView.LeadingVisual>
              <FileIcon />
            </TreeView.LeadingVisual>
            Avatar.tsx
            <TreeView.TrailingVisual>
              <StyledOcticon icon={DiffAddedIcon} color="success.fg" aria-label="added" />
            </TreeView.TrailingVisual>
          </TreeView.LinkItem>
          <TreeView.LinkItem href="#" current>
            <TreeView.LeadingVisual>
              <FileIcon />
            </TreeView.LeadingVisual>
            Button.tsx
            <TreeView.TrailingVisual>
              <StyledOcticon icon={DiffModifiedIcon} color="attention.fg" aria-label="modified" />
            </TreeView.TrailingVisual>
          </TreeView.LinkItem>
        </TreeView.SubTree>
      </TreeView.Item>
      <TreeView.LinkItem href="#">
        <TreeView.LeadingVisual>
          <FileIcon />
        </TreeView.LeadingVisual>
        package.json
        <TreeView.TrailingVisual>
          <StyledOcticon icon={DiffModifiedIcon} color="attention.fg" aria-label="modified" />
        </TreeView.TrailingVisual>
      </TreeView.LinkItem>
    </TreeView>
  </nav>
</Box>

<Box sx={{maxWidth: 400}}>
  <nav aria-label="File navigation">
    <TreeView aria-label="File navigation">
      <TreeView.LinkItem href="#">
        <TreeView.LeadingVisual>
          <TreeView.DirectoryIcon />
        </TreeView.LeadingVisual>
        src
        <TreeView.SubTree>
          <TreeView.LinkItem href="#">
            <TreeView.LeadingVisual>
              <FileIcon />
            </TreeView.LeadingVisual>
            Avatar.tsx
          </TreeView.LinkItem>
          <TreeView.LinkItem href="#" current>
            <TreeView.LeadingVisual>
              <TreeView.DirectoryIcon />
            </TreeView.LeadingVisual>
            Button
            <TreeView.SubTree>
              <TreeView.LinkItem href="#">
                <TreeView.LeadingVisual>
                  <FileIcon />
                </TreeView.LeadingVisual>
                Button.tsx
              </TreeView.LinkItem>
              <TreeView.LinkItem href="#">
                <TreeView.LeadingVisual>
                  <FileIcon />
                </TreeView.LeadingVisual>
                Button.test.tsx
              </TreeView.LinkItem>
            </TreeView.SubTree>
          </TreeView.LinkItem>
        </TreeView.SubTree>
      </TreeView.LinkItem>
      <TreeView.LinkItem href="#">
        <TreeView.LeadingVisual>
          <FileIcon />
        </TreeView.LeadingVisual>
        package.json
      </TreeView.LinkItem>
    </TreeView>
  </nav>
</Box>

<Box sx={{maxWidth: 400}}>
  <nav aria-label="File navigation">
    <TreeView aria-label="File navigation">
      <TreeView.LinkItem href="#">
        <TreeView.LeadingVisual>
          <TreeView.DirectoryIcon />
        </TreeView.LeadingVisual>
        src
        <TreeView.SubTree>
          <TreeView.LinkItem href="#">
            <TreeView.LeadingVisual>
              <FileIcon />
            </TreeView.LeadingVisual>
            Avatar.tsx
          </TreeView.LinkItem>
          <TreeView.LinkItem href="#" current>
            <TreeView.LeadingVisual>
              <TreeView.DirectoryIcon />
            </TreeView.LeadingVisual>
            Button
            <TreeView.SubTree>
              <TreeView.LinkItem href="#">
                <TreeView.LeadingVisual>
                  <FileIcon />
                </TreeView.LeadingVisual>
                Button.tsx
              </TreeView.LinkItem>
              <TreeView.LinkItem href="#">
                <TreeView.LeadingVisual>
                  <FileIcon />
                </TreeView.LeadingVisual>
                Button.test.tsx
              </TreeView.LinkItem>
            </TreeView.SubTree>
          </TreeView.LinkItem>
        </TreeView.SubTree>
      </TreeView.LinkItem>
      <TreeView.LinkItem href="#">
        <TreeView.LeadingVisual>
          <FileIcon />
        </TreeView.LeadingVisual>
        package.json
      </TreeView.LinkItem>
    </TreeView>
  </nav>
</Box>

With controlled expanded state

function ControlledTreeView() {
  const [expanded, setExpanded] = React.useState(false)

  return (
    <Box sx={{display: 'grid', gap: 2, maxWidth: 400}}>
      <Button onClick={() => setExpanded(!expanded)}>{expanded ? 'Collapse' : 'Expand'}</Button>
      <nav aria-label="File navigation">
        <TreeView aria-label="File navigation">
          <TreeView.Item expanded={expanded} onExpandedChange={setExpanded}>
            src
            <TreeView.SubTree>
              <TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
              <TreeView.LinkItem href="#" current>
                Button.tsx
              </TreeView.LinkItem>
            </TreeView.SubTree>
          </TreeView.Item>
        </TreeView>
      </nav>
    </Box>
  )
}

render(<ControlledTreeView />)

function ControlledTreeView() {
  const [expanded, setExpanded] = React.useState(false)

  return (
    <Box sx={{display: 'grid', gap: 2, maxWidth: 400}}>
      <Button onClick={() => setExpanded(!expanded)}>{expanded ? 'Collapse' : 'Expand'}</Button>
      <nav aria-label="File navigation">
        <TreeView aria-label="File navigation">
          <TreeView.Item expanded={expanded} onExpandedChange={setExpanded}>
            src
            <TreeView.SubTree>
              <TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
              <TreeView.LinkItem href="#" current>
                Button.tsx
              </TreeView.LinkItem>
            </TreeView.SubTree>
          </TreeView.Item>
        </TreeView>
      </nav>
    </Box>
  )
}

render(<ControlledTreeView />)

With stateful visuals

To render stateful visuals, pass a render function to TreeView.LeadingVisual or TreeView.TrailingVisual. The function will be called with the expanded state of the item.

<Box sx={{maxWidth: 400}}>
  <nav aria-label="File navigation">
    <TreeView aria-label="File navigation">
      <TreeView.Item>
        <TreeView.LeadingVisual>
          {({isExpanded}) => (isExpanded ? <FileDirectoryOpenFillIcon /> : <FileDirectoryFillIcon />)}
        </TreeView.LeadingVisual>
        src
        <TreeView.SubTree>
          <TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
          <TreeView.LinkItem href="#" current>
            Button.tsx
          </TreeView.LinkItem>
        </TreeView.SubTree>
      </TreeView.Item>
    </TreeView>
  </nav>
</Box>

<Box sx={{maxWidth: 400}}>
  <nav aria-label="File navigation">
    <TreeView aria-label="File navigation">
      <TreeView.Item>
        <TreeView.LeadingVisual>
          {({isExpanded}) => (isExpanded ? <FileDirectoryOpenFillIcon /> : <FileDirectoryFillIcon />)}
        </TreeView.LeadingVisual>
        src
        <TreeView.SubTree>
          <TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
          <TreeView.LinkItem href="#" current>
            Button.tsx
          </TreeView.LinkItem>
        </TreeView.SubTree>
      </TreeView.Item>
    </TreeView>
  </nav>
</Box>

Since stateful directory icons are a common use case for TreeView, we provide a TreeView.DirectoryIcon component for convenience. The previous example can be rewritten as:

<Box sx={{maxWidth: 400}}>
  <nav aria-label="File navigation">
    <TreeView aria-label="File navigation">
      <TreeView.Item>
        <TreeView.LeadingVisual>
          <TreeView.DirectoryIcon />
        </TreeView.LeadingVisual>
        src
        <TreeView.SubTree>
          <TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
          <TreeView.LinkItem href="#" current>
            Button.tsx
          </TreeView.LinkItem>
        </TreeView.SubTree>
      </TreeView.Item>
    </TreeView>
  </nav>
</Box>

<Box sx={{maxWidth: 400}}>
  <nav aria-label="File navigation">
    <TreeView aria-label="File navigation">
      <TreeView.Item>
        <TreeView.LeadingVisual>
          <TreeView.DirectoryIcon />
        </TreeView.LeadingVisual>
        src
        <TreeView.SubTree>
          <TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
          <TreeView.LinkItem href="#" current>
            Button.tsx
          </TreeView.LinkItem>
        </TreeView.SubTree>
      </TreeView.Item>
    </TreeView>
  </nav>
</Box>

With asynchronously loaded items

See Storybook for examples with asynchronously loaded items.

Props

TreeView

Name	Type	Default	Description
children Required	React.ReactNode

TreeView.Item

Name	Type	Default	Description
children Required	React.ReactNode
current	boolean	false	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.
onExpandedChange	(expanded: boolean) => void		Event handler called when the expanded state of the item changes.
onSelect	(event: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>) => void
ref	React.RefObject<HTMLElement>		A ref to the element rendered by this component.

TreeView.LinkItem

Name	Type	Default	Description
children Required	React.ReactNode
href	string		The URL that the item navigates to. `href` is passed to the underlying `<a>` element. If `as` is specified, the component may need different props. If the item contains a sub-nav, the item is rendered as a `<button>` and `href` is ignored.
current	boolean	false	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 its state.
expanded	boolean		The controlled expanded state of item. Must be used in conjunction with onExpandedChange.
onExpandedChange	(expanded: boolean) => void		Event handler called when the expanded state of the item changes.
onSelect	(event: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>) => void
ref	React.RefObject<HTMLElement>		A ref to the element rendered by this component.

TreeView.SubTree

Name Type Default Description

children

Name	Type	Default	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`: Items are neither loaded nor loading. `loading`: Currently loading items. The subtree will render a loading indicator when in this state (after a 300ms delay). `done`: Done loading items. Screen readers will announce when a subtree enters this state. `error`: An error occured while loading items.

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: Items are neither loaded nor loading.
loading: Currently loading items. The subtree will render a loading indicator when in this state (after a 300ms delay).
done: Done loading items. Screen readers will announce when a subtree enters this state.
error: An error occured while loading items.

TreeView.LeadingVisual

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

TreeView.TrailingVisual

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

TreeView.DirectoryIcon

Name	Type	Default	Description

Status

Alpha

Component props are documented on primer.style/react.
Component does not have any unnecessary third-party dependencies.
Component can adapt to different themes.
Component can adapt to different screen sizes.
Component has 100% test coverage.

Beta

Component is used in a production application.
Common usage examples are documented on primer.style/react.
Common usage examples are documented in storybook stories.
Component has been reviewed by a systems designer and any resulting issues have been addressed.
Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Stable

Component API has been stable with no breaking changes for at least one month.
Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
Component has corresponding design guidelines documented in the interface guidelines.
Component has corresponding Figma component in the Primer Web library.