Tree

A tree provides users with a way to navigate nested hierarchical information, with support for keyboard navigation and selection.

Example#

This example's MyTreeItemContent is from the Reusable Wrappers section below.

import {Button, Collection, Tree, TreeItem, TreeItemContent} from 'react-aria-components';

<Tree
  aria-label="Files"
  style={{ height: '300px' }}
  defaultExpandedKeys={['documents', 'photos', 'project']}
  selectionMode="multiple"
  defaultSelectedKeys={['photos']}
>
  <TreeItem id="documents" textValue="Documents">
    <MyTreeItemContent>
      Documents
      <Button aria-label="Info">ⓘ</Button>
    </MyTreeItemContent>
    <TreeItem id="project" textValue="Project">
      <MyTreeItemContent>
        Project
        <Button aria-label="Info">ⓘ</Button>
      </MyTreeItemContent>
      <TreeItem id="report" textValue="Weekly Report">
        <MyTreeItemContent>
          Weekly Report
          <Button aria-label="Info">ⓘ</Button>
        </MyTreeItemContent>
      </TreeItem>
    </TreeItem>
  </TreeItem>
  <TreeItem id="photos" textValue="Photos">
    <MyTreeItemContent>
      Photos
      <Button aria-label="Info">ⓘ</Button>
    </MyTreeItemContent>
    <TreeItem id="one" textValue="Image 1">
      <MyTreeItemContent>
        Image 1
        <Button aria-label="Info">ⓘ</Button>
      </MyTreeItemContent>
    </TreeItem>
    <TreeItem id="two" textValue="Image 2">
      <MyTreeItemContent>
        Image 2
        <Button aria-label="Info">ⓘ</Button>
      </MyTreeItemContent>
    </TreeItem>
  </TreeItem>
</Tree>

import {
  Button,
  Collection,
  Tree,
  TreeItem,
  TreeItemContent
} from 'react-aria-components';

<Tree
  aria-label="Files"
  style={{ height: '300px' }}
  defaultExpandedKeys={['documents', 'photos', 'project']}
  selectionMode="multiple"
  defaultSelectedKeys={['photos']}
>
  <TreeItem id="documents" textValue="Documents">
    <MyTreeItemContent>
      Documents
      <Button aria-label="Info">ⓘ</Button>
    </MyTreeItemContent>
    <TreeItem id="project" textValue="Project">
      <MyTreeItemContent>
        Project
        <Button aria-label="Info">ⓘ</Button>
      </MyTreeItemContent>
      <TreeItem id="report" textValue="Weekly Report">
        <MyTreeItemContent>
          Weekly Report
          <Button aria-label="Info">ⓘ</Button>
        </MyTreeItemContent>
      </TreeItem>
    </TreeItem>
  </TreeItem>
  <TreeItem id="photos" textValue="Photos">
    <MyTreeItemContent>
      Photos
      <Button aria-label="Info">ⓘ</Button>
    </MyTreeItemContent>
    <TreeItem id="one" textValue="Image 1">
      <MyTreeItemContent>
        Image 1
        <Button aria-label="Info">ⓘ</Button>
      </MyTreeItemContent>
    </TreeItem>
    <TreeItem id="two" textValue="Image 2">
      <MyTreeItemContent>
        Image 2
        <Button aria-label="Info">ⓘ</Button>
      </MyTreeItemContent>
    </TreeItem>
  </TreeItem>
</Tree>

import {
  Button,
  Collection,
  Tree,
  TreeItem,
  TreeItemContent
} from 'react-aria-components';

<Tree
  aria-label="Files"
  style={{
    height: '300px'
  }}
  defaultExpandedKeys={[
    'documents',
    'photos',
    'project'
  ]}
  selectionMode="multiple"
  defaultSelectedKeys={[
    'photos'
  ]}
>
  <TreeItem
    id="documents"
    textValue="Documents"
  >
    <MyTreeItemContent>
      Documents
      <Button aria-label="Info">
        ⓘ
      </Button>
    </MyTreeItemContent>
    <TreeItem
      id="project"
      textValue="Project"
    >
      <MyTreeItemContent>
        Project
        <Button aria-label="Info">
          ⓘ
        </Button>
      </MyTreeItemContent>
      <TreeItem
        id="report"
        textValue="Weekly Report"
      >
        <MyTreeItemContent>
          Weekly Report
          <Button aria-label="Info">
            ⓘ
          </Button>
        </MyTreeItemContent>
      </TreeItem>
    </TreeItem>
  </TreeItem>
  <TreeItem
    id="photos"
    textValue="Photos"
  >
    <MyTreeItemContent>
      Photos
      <Button aria-label="Info">
        ⓘ
      </Button>
    </MyTreeItemContent>
    <TreeItem
      id="one"
      textValue="Image 1"
    >
      <MyTreeItemContent>
        Image 1
        <Button aria-label="Info">
          ⓘ
        </Button>
      </MyTreeItemContent>
    </TreeItem>
    <TreeItem
      id="two"
      textValue="Image 2"
    >
      <MyTreeItemContent>
        Image 2
        <Button aria-label="Info">
          ⓘ
        </Button>
      </MyTreeItemContent>
    </TreeItem>
  </TreeItem>
</Tree>

.react-aria-Tree {
  display: flex;
  flex-direction: column;
  gap: 2px;
  overflow: auto;
  padding: 4px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--overlay-background);
  forced-color-adjust: none;
  outline: none;
  width: 250px;
  max-height: 300px;
  box-sizing: border-box;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: -1px;
  }

  .react-aria-TreeItem {
    display: flex;
    align-items: center;
    gap: 0.571rem;
    min-height: 28px;
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    --padding: 16px;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: translateZ(0);

    .react-aria-Button[slot=chevron] {
      all: unset;
      display: flex;
      visibility: hidden;
      align-items: center;
      justify-content: center;
      width: 1.3rem;
      height: 100%;
      padding-left: calc((var(--tree-item-level) - 1) * var(--padding));

      svg {
        rotate: 0deg;
        transition: rotate 200ms;
        width: 12px;
        height: 12px;
        fill: none;
        stroke: currentColor;
        stroke-width: 3px;
      }
    }

    &[data-has-child-items] .react-aria-Button[slot=chevron] {
      visibility: visible;
    }

    &[data-expanded] .react-aria-Button[slot=chevron] svg {
      rotate: 90deg;
    }

    &[data-focus-visible] {
      outline: 2px solid var(--focus-ring-color);
      outline-offset: -2px;
    }

    &[data-pressed] {
      background: var(--gray-100);
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
      --focus-ring-color: var(--highlight-foreground);

      &[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -4px;
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --highlight-hover: rgb(255 255 255 / 0.1);
        --highlight-pressed: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }

    .react-aria-Button:not([slot]) {
      margin-left: auto;
      background: transparent;
      border: none;
      font-size: 1.2rem;
      line-height: 1.2em;
      padding: 0.286rem 0.429rem;
      transition: background 200ms;

      &[data-hovered] {
        background: var(--highlight-hover);
      }

      &[data-pressed] {
        background: var(--highlight-pressed);
        box-shadow: none;
      }
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    gap: 0;

    .react-aria-TreeItem[data-selected]:has(+ [data-selected]) {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-TreeItem[data-selected] + [data-selected] {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }

  :where(.react-aria-TreeItem) .react-aria-Checkbox {
    --selected-color: var(--highlight-foreground);
    --selected-color-pressed: var(--highlight-foreground-pressed);
    --checkmark-color: var(--highlight-background);
    --background-color: var(--highlight-background);
  }
}

.react-aria-Tree {
  display: flex;
  flex-direction: column;
  gap: 2px;
  overflow: auto;
  padding: 4px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--overlay-background);
  forced-color-adjust: none;
  outline: none;
  width: 250px;
  max-height: 300px;
  box-sizing: border-box;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: -1px;
  }

  .react-aria-TreeItem {
    display: flex;
    align-items: center;
    gap: 0.571rem;
    min-height: 28px;
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    --padding: 16px;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: translateZ(0);

    .react-aria-Button[slot=chevron] {
      all: unset;
      display: flex;
      visibility: hidden;
      align-items: center;
      justify-content: center;
      width: 1.3rem;
      height: 100%;
      padding-left: calc((var(--tree-item-level) - 1) * var(--padding));

      svg {
        rotate: 0deg;
        transition: rotate 200ms;
        width: 12px;
        height: 12px;
        fill: none;
        stroke: currentColor;
        stroke-width: 3px;
      }
    }

    &[data-has-child-items] .react-aria-Button[slot=chevron] {
      visibility: visible;
    }

    &[data-expanded] .react-aria-Button[slot=chevron] svg {
      rotate: 90deg;
    }

    &[data-focus-visible] {
      outline: 2px solid var(--focus-ring-color);
      outline-offset: -2px;
    }

    &[data-pressed] {
      background: var(--gray-100);
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
      --focus-ring-color: var(--highlight-foreground);

      &[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -4px;
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --highlight-hover: rgb(255 255 255 / 0.1);
        --highlight-pressed: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }

    .react-aria-Button:not([slot]) {
      margin-left: auto;
      background: transparent;
      border: none;
      font-size: 1.2rem;
      line-height: 1.2em;
      padding: 0.286rem 0.429rem;
      transition: background 200ms;

      &[data-hovered] {
        background: var(--highlight-hover);
      }

      &[data-pressed] {
        background: var(--highlight-pressed);
        box-shadow: none;
      }
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    gap: 0;

    .react-aria-TreeItem[data-selected]:has(+ [data-selected]) {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-TreeItem[data-selected] + [data-selected] {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }

  :where(.react-aria-TreeItem) .react-aria-Checkbox {
    --selected-color: var(--highlight-foreground);
    --selected-color-pressed: var(--highlight-foreground-pressed);
    --checkmark-color: var(--highlight-background);
    --background-color: var(--highlight-background);
  }
}

.react-aria-Tree {
  display: flex;
  flex-direction: column;
  gap: 2px;
  overflow: auto;
  padding: 4px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--overlay-background);
  forced-color-adjust: none;
  outline: none;
  width: 250px;
  max-height: 300px;
  box-sizing: border-box;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: -1px;
  }

  .react-aria-TreeItem {
    display: flex;
    align-items: center;
    gap: 0.571rem;
    min-height: 28px;
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    --padding: 16px;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: translateZ(0);

    .react-aria-Button[slot=chevron] {
      all: unset;
      display: flex;
      visibility: hidden;
      align-items: center;
      justify-content: center;
      width: 1.3rem;
      height: 100%;
      padding-left: calc((var(--tree-item-level) - 1) * var(--padding));

      svg {
        rotate: 0deg;
        transition: rotate 200ms;
        width: 12px;
        height: 12px;
        fill: none;
        stroke: currentColor;
        stroke-width: 3px;
      }
    }

    &[data-has-child-items] .react-aria-Button[slot=chevron] {
      visibility: visible;
    }

    &[data-expanded] .react-aria-Button[slot=chevron] svg {
      rotate: 90deg;
    }

    &[data-focus-visible] {
      outline: 2px solid var(--focus-ring-color);
      outline-offset: -2px;
    }

    &[data-pressed] {
      background: var(--gray-100);
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
      --focus-ring-color: var(--highlight-foreground);

      &[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -4px;
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --highlight-hover: rgb(255 255 255 / 0.1);
        --highlight-pressed: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }

    .react-aria-Button:not([slot]) {
      margin-left: auto;
      background: transparent;
      border: none;
      font-size: 1.2rem;
      line-height: 1.2em;
      padding: 0.286rem 0.429rem;
      transition: background 200ms;

      &[data-hovered] {
        background: var(--highlight-hover);
      }

      &[data-pressed] {
        background: var(--highlight-pressed);
        box-shadow: none;
      }
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    gap: 0;

    .react-aria-TreeItem[data-selected]:has(+ [data-selected]) {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-TreeItem[data-selected] + [data-selected] {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }

  :where(.react-aria-TreeItem) .react-aria-Checkbox {
    --selected-color: var(--highlight-foreground);
    --selected-color-pressed: var(--highlight-foreground-pressed);
    --checkmark-color: var(--highlight-background);
    --background-color: var(--highlight-background);
  }
}

Features#

A tree can be built using the <ul>, <li>, and <ol>, but is very limited in functionality especially when it comes to user interactions. HTML lists are meant for static content, rather than hierarchies with rich interactions like focusable elements within cells, keyboard navigation, item selection, sorting, etc. Tree helps achieve accessible and interactive tree components that can be styled as needed.

• Item selection – Single or multiple selection, with optional checkboxes, disabled items, and both toggle and replace selection behaviors.
• Interactive children – Tree items may include interactive elements such as buttons, menus, etc.
• Actions – Items support optional actions such as navigation via click, tap, double click, or Enter key.
• Keyboard navigation – Tree items and focusable children can be navigated using the arrow keys, along with page up/down, home/end, etc. Typeahead, auto scrolling, and selection modifier keys are supported as well.
• Drag and drop – Tree supports drag and drop to reorder, move, insert, or update items via mouse, touch, keyboard, and screen reader interactions.
• Virtualized scrolling – Use Virtualizer to improve performance of large lists by rendering only the visible items.
• Touch friendly – Selection and actions adapt their behavior depending on the device. For example, selection is activated via long press on touch when item actions are present.
• Accessible – Follows the ARIA treegrid pattern, with additional selection announcements via an ARIA live region. Extensively tested across many devices and assistive technologies to ensure announcements and behaviors are consistent.

Anatomy#

A Tree consists of a container element, with items containing data inside. The items within a tree may contain focusable elements or plain text content. Each item may also contain a button to toggle the expandable state of that item.

If the tree supports item selection, each item can optionally include a selection checkbox.

import {Button, Checkbox, Tree, TreeItem, TreeItemContent} from 'react-aria-components';

<Tree>
  <TreeItem>
    <TreeItemContent>
      <Button slot="chevron" />
      <Checkbox slot="selection" />
      <Button slot="drag" />
    </TreeItemContent>
    <TreeItem>
      {/* ... */}
    </TreeItem>
  </TreeItem>
</Tree>

import {
  Button,
  Checkbox,
  Tree,
  TreeItem,
  TreeItemContent
} from 'react-aria-components';

<Tree>
  <TreeItem>
    <TreeItemContent>
      <Button slot="chevron" />
      <Checkbox slot="selection" />
      <Button slot="drag" />
    </TreeItemContent>
    <TreeItem>
      {/* ... */}
    </TreeItem>
  </TreeItem>
</Tree>

import {
  Button,
  Checkbox,
  Tree,
  TreeItem,
  TreeItemContent
} from 'react-aria-components';

<Tree>
  <TreeItem>
    <TreeItemContent>
      <Button slot="chevron" />
      <Checkbox slot="selection" />
      <Button slot="drag" />
    </TreeItemContent>
    <TreeItem>
      {/* ... */}
    </TreeItem>
  </TreeItem>
</Tree>

Concepts#

Tree makes use of the following concepts:

Composed components#

A Tree uses the following components, which may also be used standalone or reused in other components.

Examples#

File System Tree

A tree with multiple selection and nested items.

Starter kits#

To help kick-start your project, we offer starter kits that include example implementations of all React Aria components with various styling solutions. All components are fully styled, including support for dark mode, high contrast mode, and all UI states. Each starter comes with a pre-configured Storybook that you can experiment with, or use as a starting point for your own component library.

Reusable wrappers#

If you will use a Tree in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

import type {TreeItemContentProps, TreeItemContentRenderProps} from 'react-aria-components';
import {Button} from 'react-aria-components';

function MyTreeItemContent(
  props: Omit<TreeItemContentProps, 'children'> & { children?: React.ReactNode }
) {
  return (
    <TreeItemContent>
      {(
        { hasChildItems, selectionBehavior, selectionMode, allowsDragging }:
          TreeItemContentRenderProps
      ) => (
        <>
          {allowsDragging && <Button slot="drag">≡</Button>}
          {selectionBehavior === 'toggle' && selectionMode !== 'none' && (
            <MyCheckbox slot="selection" />
          )}
          <Button slot="chevron">
            <svg viewBox="0 0 24 24">
              <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
            </svg>
          </Button>
          {props.children}
        </>
      )}
    </TreeItemContent>
  );
}

import type {
  TreeItemContentProps,
  TreeItemContentRenderProps
} from 'react-aria-components';
import {Button} from 'react-aria-components';

function MyTreeItemContent(
  props: Omit<TreeItemContentProps, 'children'> & {
    children?: React.ReactNode;
  }
) {
  return (
    <TreeItemContent>
      {(
        {
          hasChildItems,
          selectionBehavior,
          selectionMode,
          allowsDragging
        }: TreeItemContentRenderProps
      ) => (
        <>
          {allowsDragging && <Button slot="drag">≡</Button>}
          {selectionBehavior === 'toggle' &&
            selectionMode !== 'none' && (
            <MyCheckbox slot="selection" />
          )}
          <Button slot="chevron">
            <svg viewBox="0 0 24 24">
              <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
            </svg>
          </Button>
          {props.children}
        </>
      )}
    </TreeItemContent>
  );
}

import type {
  TreeItemContentProps,
  TreeItemContentRenderProps
} from 'react-aria-components';
import {Button} from 'react-aria-components';

function MyTreeItemContent(
  props:
    & Omit<
      TreeItemContentProps,
      'children'
    >
    & {
      children?:
        React.ReactNode;
    }
) {
  return (
    <TreeItemContent>
      {(
        {
          hasChildItems,
          selectionBehavior,
          selectionMode,
          allowsDragging
        }: TreeItemContentRenderProps
      ) => (
        <>
          {allowsDragging &&
            (
              <Button slot="drag">
                ≡
              </Button>
            )}
          {selectionBehavior ===
              'toggle' &&
            selectionMode !==
              'none' &&
            (
              <MyCheckbox slot="selection" />
            )}
          <Button slot="chevron">
            <svg viewBox="0 0 24 24">
              <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
            </svg>
          </Button>
          {props
            .children}
        </>
      )}
    </TreeItemContent>
  );
}

The TreeItem can also be wrapped. This example accepts a title prop and renders the TreeItemContent automatically.

import {TreeItemProps} from 'react-aria-components';

interface MyTreeItemProps extends Partial<TreeItemProps> {
  title: string
}

function MyTreeItem(props: MyTreeItemProps) {
  return (
    <TreeItem textValue={props.title} {...props}>
      <MyTreeItemContent>
        {props.title}
      </MyTreeItemContent>
      {props.children}
    </TreeItem>
  );
}

import {TreeItemProps} from 'react-aria-components';

interface MyTreeItemProps extends Partial<TreeItemProps> {
  title: string
}

function MyTreeItem(props: MyTreeItemProps) {
  return (
    <TreeItem textValue={props.title} {...props}>
      <MyTreeItemContent>
        {props.title}
      </MyTreeItemContent>
      {props.children}
    </TreeItem>
  );
}

import {TreeItemProps} from 'react-aria-components';

interface MyTreeItemProps
  extends
    Partial<
      TreeItemProps
    > {
  title: string;
}

function MyTreeItem(
  props: MyTreeItemProps
) {
  return (
    <TreeItem
      textValue={props
        .title}
      {...props}
    >
      <MyTreeItemContent>
        {props.title}
      </MyTreeItemContent>
      {props.children}
    </TreeItem>
  );
}

Now we can render a Tree using far less code.

<Tree
  aria-label="Files"
  style={{ height: '300px' }}
  defaultExpandedKeys={['documents', 'photos', 'project']}
>
  <MyTreeItem title="Documents">
    <MyTreeItem title="Project">
      <MyTreeItem title="Weekly Report" />
    </MyTreeItem>
  </MyTreeItem>
  <MyTreeItem title="Photos">
    <MyTreeItem title="Image 1" />
    <MyTreeItem title="Image 2" />
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Files"
  style={{ height: '300px' }}
  defaultExpandedKeys={['documents', 'photos', 'project']}
>
  <MyTreeItem title="Documents">
    <MyTreeItem title="Project">
      <MyTreeItem title="Weekly Report" />
    </MyTreeItem>
  </MyTreeItem>
  <MyTreeItem title="Photos">
    <MyTreeItem title="Image 1" />
    <MyTreeItem title="Image 2" />
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Files"
  style={{
    height: '300px'
  }}
  defaultExpandedKeys={[
    'documents',
    'photos',
    'project'
  ]}
>
  <MyTreeItem title="Documents">
    <MyTreeItem title="Project">
      <MyTreeItem title="Weekly Report" />
    </MyTreeItem>
  </MyTreeItem>
  <MyTreeItem title="Photos">
    <MyTreeItem title="Image 1" />
    <MyTreeItem title="Image 2" />
  </MyTreeItem>
</Tree>

Content#

So far, our examples have shown static collections where the data is hard coded. Dynamic collections, as shown below, can be used when the tree data comes from an external data source such as an API, or updates over time. In the example below, data for each item is provided to the tree via a render function.

import type {TreeProps} from 'react-aria-components';
import {MyCheckbox} from './Checkbox';

let items = [
  {id: '1', title: 'Documents', type: 'directory', children: [
    {id: '2', title: 'Project', type: 'directory', children: [
      {id: '3', title: 'Weekly Report', type: 'file', children: []},
      {id: '4', title: 'Budget', type: 'file', children: []}
    ]}
  ]},
  {id: '5', title: 'Photos', type: 'directory', children: [
    {id: '6', title: 'Image 1', type: 'file', children: []},
    {id: '7', title: 'Image 2', type: 'file', children: []}
  ]}
];

interface FileType {
  id: string,
  title: string,
  type: 'directory' | 'file',
  children: FileType[]
}

function FileTree(props: TreeProps<FileType>) {
  return (
    <Tree
      aria-label="Files"
      defaultExpandedKeys={[1, 4]}
      items={items}      selectionMode="multiple"
      {...props}>
      {function renderItem(item) {        return (
          <TreeItem textValue={item.title}>
            <MyTreeItemContent>
              {item.title}
              <Button
                aria-label="Info"
                onPress={() => alert(`Info for ${item.title}...`)}>
                ⓘ
              </Button>
            </MyTreeItemContent>
            <Collection items={item.children}>
              {/* recursively render children */}
              {renderItem}            </Collection>
          </TreeItem>
        );
      }}
    </Tree>
  )
}

import type {TreeProps} from 'react-aria-components';
import {MyCheckbox} from './Checkbox';

let items = [
  {
    id: '1',
    title: 'Documents',
    type: 'directory',
    children: [
      {
        id: '2',
        title: 'Project',
        type: 'directory',
        children: [
          {
            id: '3',
            title: 'Weekly Report',
            type: 'file',
            children: []
          },
          {
            id: '4',
            title: 'Budget',
            type: 'file',
            children: []
          }
        ]
      }
    ]
  },
  {
    id: '5',
    title: 'Photos',
    type: 'directory',
    children: [
      {
        id: '6',
        title: 'Image 1',
        type: 'file',
        children: []
      },
      {
        id: '7',
        title: 'Image 2',
        type: 'file',
        children: []
      }
    ]
  }
];

interface FileType {
  id: string;
  title: string;
  type: 'directory' | 'file';
  children: FileType[];
}

function FileTree(props: TreeProps<FileType>) {
  return (
    <Tree
      aria-label="Files"
      defaultExpandedKeys={[1, 4]}
      items={items}      selectionMode="multiple"
      {...props}
    >
      {function renderItem(item) {        return (
          <TreeItem textValue={item.title}>
            <MyTreeItemContent>
              {item.title}
              <Button
                aria-label="Info"
                onPress={() =>
                  alert(`Info for ${item.title}...`)}
              >
                ⓘ
              </Button>
            </MyTreeItemContent>
            <Collection items={item.children}>
              {/* recursively render children */}
              {renderItem}            </Collection>
          </TreeItem>
        );
      }}
    </Tree>
  );
}

import type {TreeProps} from 'react-aria-components';
import {MyCheckbox} from './Checkbox';

let items = [
  {
    id: '1',
    title: 'Documents',
    type: 'directory',
    children: [
      {
        id: '2',
        title: 'Project',
        type:
          'directory',
        children: [
          {
            id: '3',
            title:
              'Weekly Report',
            type: 'file',
            children: []
          },
          {
            id: '4',
            title:
              'Budget',
            type: 'file',
            children: []
          }
        ]
      }
    ]
  },
  {
    id: '5',
    title: 'Photos',
    type: 'directory',
    children: [
      {
        id: '6',
        title: 'Image 1',
        type: 'file',
        children: []
      },
      {
        id: '7',
        title: 'Image 2',
        type: 'file',
        children: []
      }
    ]
  }
];

interface FileType {
  id: string;
  title: string;
  type:
    | 'directory'
    | 'file';
  children: FileType[];
}

function FileTree(
  props: TreeProps<
    FileType
  >
) {
  return (
    <Tree
      aria-label="Files"
      defaultExpandedKeys={[
        1,
        4
      ]}
      items={items}      selectionMode="multiple"
      {...props}
    >
      {function renderItem(
        item
      ) {        return (
          <TreeItem
            textValue={item
              .title}
          >
            <MyTreeItemContent>
              {item
                .title}
              <Button
                aria-label="Info"
                onPress={() =>
                  alert(
                    `Info for ${item.title}...`
                  )}
              >
                ⓘ
              </Button>
            </MyTreeItemContent>
            <Collection
              items={item
                .children}
            >
              {/* recursively render children */}
              {renderItem}            </Collection>
          </TreeItem>
        );
      }}
    </Tree>
  );
}

Selection#

Single selection#

By default, Tree doesn't allow item selection but this can be enabled using the selectionMode prop. Use defaultSelectedKeys to provide a default set of selected items. Note that the value of the selected keys must match the id prop of the item.

The example below enables single selection mode and uses defaultSelectedKeys to select the item with id equal to 2. A user can click on a different item to change the selection or click on the same item again to deselect it entirely.

// Using the example above
<FileTree
  selectionMode="single"
  defaultSelectedKeys={[2]}
  defaultExpandedKeys={[1]}
/>

// Using the example above
<FileTree
  selectionMode="single"
  defaultSelectedKeys={[2]}
  defaultExpandedKeys={[1]}
/>

// Using the example above
<FileTree
  selectionMode="single"
  defaultSelectedKeys={[
    2
  ]}
  defaultExpandedKeys={[
    1
  ]}
/>

Multiple selection#

Multiple selection can be enabled by setting selectionMode to multiple.

// Using the example above
<FileTree
  selectionMode="multiple"
  defaultSelectedKeys={[2, 4]}
  defaultExpandedKeys={[1]}
/>

// Using the example above
<FileTree
  selectionMode="multiple"
  defaultSelectedKeys={[2, 4]}
  defaultExpandedKeys={[1]}
/>

// Using the example above
<FileTree
  selectionMode="multiple"
  defaultSelectedKeys={[
    2,
    4
  ]}
  defaultExpandedKeys={[
    1
  ]}
/>

Disallow empty selection#

Tree also supports a disallowEmptySelection prop which forces the user to have at least one item in the Tree selected at all times. In this mode, if a single item is selected and the user presses it, it will not be deselected.

// Using the example above
<FileTree
  selectionMode="single"
  defaultSelectedKeys={[2]}
  defaultExpandedKeys={[1]}
  disallowEmptySelection
/>

// Using the example above
<FileTree
  selectionMode="single"
  defaultSelectedKeys={[2]}
  defaultExpandedKeys={[1]}
  disallowEmptySelection
/>

// Using the example above
<FileTree
  selectionMode="single"
  defaultSelectedKeys={[
    2
  ]}
  defaultExpandedKeys={[
    1
  ]}
  disallowEmptySelection
/>

Controlled selection#

To programmatically control item selection, use the selectedKeys prop paired with the onSelectionChange callback. The id prop from the selected items will be passed into the callback when the item is pressed, allowing you to update state accordingly.

import type {Selection} from 'react-aria-components';

interface Pokemon {
  id: number,
  name: string,
  children?: Pokemon[]
}

interface PokemonEvolutionTreeProps<T> extends TreeProps<T> {
  items?: T[],
  renderEmptyState?: () => string
}

function PokemonEvolutionTree(
  props: PokemonEvolutionTreeProps<Pokemon>
) {
  let items: Pokemon[] = props.items ?? [
    {id: 1, name: 'Bulbasaur', children: [
      {id: 2, name: 'Ivysaur', children: [
        {id: 3, name: 'Venusaur'}
      ]}
    ]},
    {id: 4, name: 'Charmander', children: [
      {id: 5, name: 'Charmeleon', children: [
        {id: 6, name: 'Charizard'}
      ]}
    ]},
    {id: 7, name: 'Squirtle', children: [
      {id: 8, name: 'Wartortle', children: [
        {id: 9, name: 'Blastoise'}
      ]}
    ]}
  ];

  let [selectedKeys, setSelectedKeys] =
    React.useState<Selection>(new Set());
  return (
    <Tree
      aria-label="Pokemon evolution tree"
      style={{height: '300px'}}
      items={items}
      defaultExpandedKeys={[1, 2]}
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}      {...props}
    >
      {function renderItem(item) {
        return (
          <MyTreeItem title={item.name}>
            <Collection items={item.children}>
              {renderItem}
            </Collection>
          </MyTreeItem>
        );
      }}
    </Tree>
  );
}

<PokemonEvolutionTree selectionMode="multiple" />

import type {Selection} from 'react-aria-components';

interface Pokemon {
  id: number;
  name: string;
  children?: Pokemon[];
}

interface PokemonEvolutionTreeProps<T>
  extends TreeProps<T> {
  items?: T[];
  renderEmptyState?: () => string;
}

function PokemonEvolutionTree(
  props: PokemonEvolutionTreeProps<Pokemon>
) {
  let items: Pokemon[] = props.items ?? [
    {
      id: 1,
      name: 'Bulbasaur',
      children: [
        {
          id: 2,
          name: 'Ivysaur',
          children: [
            { id: 3, name: 'Venusaur' }
          ]
        }
      ]
    },
    {
      id: 4,
      name: 'Charmander',
      children: [
        {
          id: 5,
          name: 'Charmeleon',
          children: [
            { id: 6, name: 'Charizard' }
          ]
        }
      ]
    },
    {
      id: 7,
      name: 'Squirtle',
      children: [
        {
          id: 8,
          name: 'Wartortle',
          children: [
            { id: 9, name: 'Blastoise' }
          ]
        }
      ]
    }
  ];

  let [selectedKeys, setSelectedKeys] = React.useState<
    Selection
  >(new Set());
  return (
    <Tree
      aria-label="Pokemon evolution tree"
      style={{ height: '300px' }}
      items={items}
      defaultExpandedKeys={[1, 2]}
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}      ...props}
    >
      {function renderItem(item) {
        return (
          <MyTreeItem title={item.name}>
            <Collection items={item.children}>
              {renderItem}
            </Collection>
          </MyTreeItem>
        );
      }}
    </Tree>
  );
}

<PokemonEvolutionTree selectionMode="multiple" />

import type {Selection} from 'react-aria-components';

interface Pokemon {
  id: number;
  name: string;
  children?: Pokemon[];
}

interface PokemonEvolutionTreeProps<
  T
> extends TreeProps<T> {
  items?: T[];
  renderEmptyState?:
    () => string;
}

function PokemonEvolutionTree(
  props:
    PokemonEvolutionTreeProps<
      Pokemon
    >
) {
  let items: Pokemon[] =
    props.items ?? [
      {
        id: 1,
        name:
          'Bulbasaur',
        children: [
          {
            id: 2,
            name:
              'Ivysaur',
            children: [
              {
                id: 3,
                name:
                  'Venusaur'
              }
            ]
          }
        ]
      },
      {
        id: 4,
        name:
          'Charmander',
        children: [
          {
            id: 5,
            name:
              'Charmeleon',
            children: [
              {
                id: 6,
                name:
                  'Charizard'
              }
            ]
          }
        ]
      },
      {
        id: 7,
        name: 'Squirtle',
        children: [
          {
            id: 8,
            name:
              'Wartortle',
            children: [
              {
                id: 9,
                name:
                  'Blastoise'
              }
            ]
          }
        ]
      }
    ];

  let [
    selectedKeys,
    setSelectedKeys
  ] = React.useState<
    Selection
  >(new Set());
  return (
    <Tree
      aria-label="Pokemon evolution tree"
      style={{
        height: '300px'
      }}
      items={items}
      defaultExpandedKeys={[
        1,
        2
      ]}
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}      ...props}
    >
      {function renderItem(
        item
      ) {
        return (
          <MyTreeItem
            title={item
              .name}
          >
            <Collection
              items={item
                .children}
            >
              {renderItem}
            </Collection>
          </MyTreeItem>
        );
      }}
    </Tree>
  );
}

<PokemonEvolutionTree selectionMode="multiple" />

Selection behavior#

By default, Tree uses the "toggle" selection behavior, which behaves like a checkbox group: clicking, tapping, or pressing the Space or Enter keys toggles selection for the focused item. Using the arrow keys moves focus but does not change selection. The "toggle" selection mode is often paired with checkboxes in each item as an explicit affordance for selection.

When the selectionBehavior prop is set to "replace", clicking an item with the mouse replaces the selection with only that item. Using the arrow keys moves both focus and selection. To select multiple items, modifier keys such as Ctrl, Cmd, and Shift can be used. To move focus without moving selection, the Ctrl key on Windows or the Option key on macOS can be held while pressing the arrow keys. Holding this modifier while pressing the Space key toggles selection for the focused item, which allows multiple selection of non-contiguous items. On touch screen devices, selection always behaves as toggle since modifier keys may not be available. This behavior emulates native platforms such as macOS and Windows and is often used when checkboxes in each item are not desired.

<PokemonEvolutionTree selectionMode="multiple" selectionBehavior="replace" />

<PokemonEvolutionTree
  selectionMode="multiple"
  selectionBehavior="replace"
/>

<PokemonEvolutionTree
  selectionMode="multiple"
  selectionBehavior="replace"
/>

Item actions#

Tree supports item actions via the onAction prop, which is useful for functionality such as navigation. In the default "toggle" selection behavior, when nothing is selected, clicking or tapping the item triggers the item action. When at least one item is selected, the tree is in selection mode, and clicking or tapping an item toggles the selection. Actions may also be triggered via the Enter key, and selection using the Space key.

This behavior is slightly different in the "replace" selection behavior, where single clicking selects the item and actions are performed via double click. On touch devices, the action becomes the primary tap interaction, and a long press enters into selection mode, which temporarily swaps the selection behavior to "toggle" to perform selection (you may wish to display checkboxes when this happens). Deselecting all items exits selection mode and reverts the selection behavior back to "replace". Keyboard behaviors are unaffected.

<div style={{display: 'flex', flexWrap: 'wrap', gap: '24px'}}>
  <PokemonEvolutionTree
    aria-label="Pokemon tree with item actions and toggle selection behavior"
    onAction={key => alert(`Opening item ${key}...`)}    selectionMode="multiple" />
  <PokemonEvolutionTree
    aria-label="Pokemon tree with item actions and replace selection behavior"
    onAction={key => alert(`Opening item ${key}...`)}
    selectionBehavior="replace"    selectionMode="multiple" />
</div>

<div
  style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '24px'
  }}
>
  <PokemonEvolutionTree
    aria-label="Pokemon tree with item actions and toggle selection behavior"
    onAction={(key) => alert(`Opening item ${key}...`)}    selectionMode="multiple"
  />
  <PokemonEvolutionTree
    aria-label="Pokemon tree with item actions and replace selection behavior"
    onAction={(key) => alert(`Opening item ${key}...`)}
    selectionBehavior="replace"    selectionMode="multiple"
  />
</div>

<div
  style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '24px'
  }}
>
  <PokemonEvolutionTree
    aria-label="Pokemon tree with item actions and toggle selection behavior"
    onAction={(key) =>
      alert(
        `Opening item ${key}...`
      )}    selectionMode="multiple"
  />
  <PokemonEvolutionTree
    aria-label="Pokemon tree with item actions and replace selection behavior"
    onAction={(key) =>
      alert(
        `Opening item ${key}...`
      )}
    selectionBehavior="replace"    selectionMode="multiple"
  />
</div>

Items may also have an action specified by directly applying onAction on the TreeItem itself. This may be especially convenient in static collections. If onAction is also provided to the Tree, both the tree's and the item's onAction are called.

<Tree
  aria-label="Tree with onAction applied on the items directly"
  style={{ height: '300px' }}
  defaultExpandedKeys={['bulbasaur', 'ivysaur']}
>
  <MyTreeItem
    onAction={() => alert(`Opening Bulbasaur...`)}    id="bulbasaur"
    title="Bulbasaur"
  >
    <MyTreeItem
      onAction={() => alert(`Opening Ivysaur...`)}
      id="ivysaur"
      title="Ivysaur"
    >
      <MyTreeItem
        onAction={() => alert(`Opening Venusaur...`)}
        id="venusaur"
        title="Venusaur"
      />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Tree with onAction applied on the items directly"
  style={{ height: '300px' }}
  defaultExpandedKeys={['bulbasaur', 'ivysaur']}
>
  <MyTreeItem
    onAction={() => alert(`Opening Bulbasaur...`)}    id="bulbasaur"
    title="Bulbasaur"
  >
    <MyTreeItem
      onAction={() => alert(`Opening Ivysaur...`)}
      id="ivysaur"
      title="Ivysaur"
    >
      <MyTreeItem
        onAction={() => alert(`Opening Venusaur...`)}
        id="venusaur"
        title="Venusaur"
      />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Tree with onAction applied on the items directly"
  style={{
    height: '300px'
  }}
  defaultExpandedKeys={[
    'bulbasaur',
    'ivysaur'
  ]}
>
  <MyTreeItem
    onAction={() =>
      alert(
        `Opening Bulbasaur...`
      )}    id="bulbasaur"
    title="Bulbasaur"
  >
    <MyTreeItem
      onAction={() =>
        alert(
          `Opening Ivysaur...`
        )}
      id="ivysaur"
      title="Ivysaur"
    >
      <MyTreeItem
        onAction={() =>
          alert(
            `Opening Venusaur...`
          )}
        id="venusaur"
        title="Venusaur"
      />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

Links#

Tree items may also be links to another page or website. This can be achieved by passing the href prop to the <TreeItem> component. Links behave the same way as described above for item actions depending on the selectionMode and selectionBehavior.

<Tree
  aria-label="Tree with onAction applied on the items directly"
  style={{ height: '200px' }}
  defaultExpandedKeys={['bulbasaur', 'ivysaur']}
>
  <MyTreeItem
    href="https://pokemondb.net/pokedex/bulbasaur"
    target="_blank"    id="bulbasaur"
    title="Bulbasaur"
  >
    <MyTreeItem
      id="ivysaur"
      title="Ivysaur"
      href="https://pokemondb.net/pokedex/ivysaur"
      target="_blank"
    >
      <MyTreeItem
        id="venusaur"
        title="Venusaur"
        href="https://pokemondb.net/pokedex/venusaur"
        target="_blank"
      />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Tree with onAction applied on the items directly"
  style={{ height: '200px' }}
  defaultExpandedKeys={['bulbasaur', 'ivysaur']}
>
  <MyTreeItem
    href="https://pokemondb.net/pokedex/bulbasaur"
    target="_blank"    id="bulbasaur"
    title="Bulbasaur"
  >
    <MyTreeItem
      id="ivysaur"
      title="Ivysaur"
      href="https://pokemondb.net/pokedex/ivysaur"
      target="_blank"
    >
      <MyTreeItem
        id="venusaur"
        title="Venusaur"
        href="https://pokemondb.net/pokedex/venusaur"
        target="_blank"
      />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Tree with onAction applied on the items directly"
  style={{
    height: '200px'
  }}
  defaultExpandedKeys={[
    'bulbasaur',
    'ivysaur'
  ]}
>
  <MyTreeItem
    href="https://pokemondb.net/pokedex/bulbasaur"
    target="_blank"    id="bulbasaur"
    title="Bulbasaur"
  >
    <MyTreeItem
      id="ivysaur"
      title="Ivysaur"
      href="https://pokemondb.net/pokedex/ivysaur"
      target="_blank"
    >
      <MyTreeItem
        id="venusaur"
        title="Venusaur"
        href="https://pokemondb.net/pokedex/venusaur"
        target="_blank"
      />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

Client side routing#

The <TreeItem> component works with frameworks and client side routers like Next.js and React Router. As with other React Aria components that support links, this works via the RouterProvider component at the root of your app. See the client side routing guide to learn how to set this up.

Disabled items#

A TreeItem can be disabled with the isDisabled prop. This will disable all interactions on the item unless the disabledBehavior prop on Tree is used to change this behavior. Note that you are responsible for the styling of disabled items, however, the selection checkbox will be automatically disabled.

<Tree
  aria-label="Tree with disabled items"
  style={{ height: '100px' }}
  defaultExpandedKeys={['bulbasaur']}
>
  <MyTreeItem id="bulbasaur" title="Bulbasaur">
    <MyTreeItem id="ivysaur" title="Ivysaur" isDisabled>      <MyTreeItem id="venusaur" title="Venusaur" />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Tree with disabled items"
  style={{ height: '100px' }}
  defaultExpandedKeys={['bulbasaur']}
>
  <MyTreeItem id="bulbasaur" title="Bulbasaur">
    <MyTreeItem id="ivysaur" title="Ivysaur" isDisabled>      <MyTreeItem id="venusaur" title="Venusaur" />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Tree with disabled items"
  style={{
    height: '100px'
  }}
  defaultExpandedKeys={[
    'bulbasaur'
  ]}
>
  <MyTreeItem
    id="bulbasaur"
    title="Bulbasaur"
  >
    <MyTreeItem
      id="ivysaur"
      title="Ivysaur"
      isDisabled
    >      <MyTreeItem
        id="venusaur"
        title="Venusaur"
      />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

When disabledBehavior is set to selection, interactions such as focus, dragging, or actions can still be performed on disabled rows.

<Tree
  aria-label="Tree with disabled items"
  style={{height: '100px'}}
  selectionMode="multiple"
  defaultExpandedKeys={['bulbasaur']}
  disabledBehavior="selection">
  <MyTreeItem id="bulbasaur" title="Bulbasaur">
    <MyTreeItem id="ivysaur" title="Ivysaur" isDisabled>      <MyTreeItem id="venusaur" title="Venusaur" />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Tree with disabled items"
  style={{height: '100px'}}
  selectionMode="multiple"
  defaultExpandedKeys={['bulbasaur']}
  disabledBehavior="selection">
  <MyTreeItem id="bulbasaur" title="Bulbasaur">
    <MyTreeItem id="ivysaur" title="Ivysaur" isDisabled>      <MyTreeItem id="venusaur" title="Venusaur" />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

<Tree
  aria-label="Tree with disabled items"
  style={{
    height: '100px'
  }}
  selectionMode="multiple"
  defaultExpandedKeys={[
    'bulbasaur'
  ]}
  disabledBehavior="selection">
  <MyTreeItem
    id="bulbasaur"
    title="Bulbasaur"
  >
    <MyTreeItem
      id="ivysaur"
      title="Ivysaur"
      isDisabled
    >      <MyTreeItem
        id="venusaur"
        title="Venusaur"
      />
    </MyTreeItem>
  </MyTreeItem>
</Tree>

In dynamic collections, it may be more convenient to use the disabledKeys prop at the Tree level instead of isDisabled on individual items. This accepts a list of item ids that are disabled. An item is considered disabled if its key exists in disabledKeys or if it has isDisabled.

// Using the same tree as above
<PokemonEvolutionTree selectionMode="multiple" disabledKeys={[3]} />

// Using the same tree as above
<PokemonEvolutionTree
  selectionMode="multiple"
  disabledKeys={[3]}
/>

// Using the same tree as above
<PokemonEvolutionTree
  selectionMode="multiple"
  disabledKeys={[3]}
/>

Empty state#

Use the renderEmptyState prop to customize what the Tree will display if there are no items.

<Tree
  aria-label="Search results"
  renderEmptyState={() => 'No results found.'}
  style={{ height: '100px' }}
>
  {[]}
</Tree>

<Tree
  aria-label="Search results"
  renderEmptyState={() => 'No results found.'}
  style={{ height: '100px' }}
>
  {[]}
</Tree>

<Tree
  aria-label="Search results"
  renderEmptyState={() =>
    'No results found.'}
  style={{
    height: '100px'
  }}
>
  {[]}
</Tree>

.react-aria-Tree {
  &[data-empty] {
    display: flex;
    align-items: center;
    justify-content: center;
    font-style: italic;
  }
}

.react-aria-Tree {
  &[data-empty] {
    display: flex;
    align-items: center;
    justify-content: center;
    font-style: italic;
  }
}

.react-aria-Tree {
  &[data-empty] {
    display: flex;
    align-items: center;
    justify-content: center;
    font-style: italic;
  }
}

Drag and drop beta#

Tree supports drag and drop interactions when the dragAndDropHooks prop is provided using the useDragAndDrop hook. Users can drop data on the tree as a whole, on individual items, insert new items between existing ones, or move items within the tree hierarchy.

React Aria supports traditional mouse and touch based drag and drop, but also implements keyboard and screen reader friendly interactions. Users can press Enter on a draggable element to enter drag and drop mode. Then, they can press Tab to navigate between drop targets. A droppable collection is treated as a single drop target, so that users can easily tab past it to get to the next drop target. Within a droppable tree, keys such as ArrowDown and ArrowUp can be used to select a drop position, such as on an item, or between items.

Items with children can be expanded or collapsed during keyboard drag and drop mode by using the ArrowRight and ArrowLeft keys, or the Option (Alt on Windows) + Enter keys. Screen reader users can expand and collapse items with children by navigating to and activating a visually hidden button that gets announced.

Draggable tree items must include a focusable drag handle using a <Button slot="drag">. This enables keyboard and screen reader users to initiate drag and drop. The MyTreeItemContent component defined in the reusable wrappers section above can be extended to include this automatically when the tree allows dragging.

See the drag and drop introduction to learn more.

Moving between levels#

The onMove event handler allows reordering items within a level, as well as moving items to a different level. It supports dropping both on and between items. The getItems function must also be implemented for items to become draggable. See below for more details.

This uses useTreeData from React Stately to manage the tree data. Note that useTreeData is a convenience hook, not a requirement. You can manage your state however you wish.

function Example() {
  let tree = useTreeData({
    initialItems: items
  });

  let { dragAndDropHooks } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map((key) => ({
        'text/plain': tree.getItem(key).value.title
      })),
    onMove(e) {
      if (e.target.dropPosition === 'before') {
        tree.moveBefore(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'after') {
        tree.moveAfter(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'on') {
        // Move items to become children of the target
        let targetNode = tree.getItem(e.target.key);
        if (targetNode) {
          let targetIndex = targetNode.children
            ? targetNode.children.length
            : 0;
          let keyArray = Array.from(e.keys);
          for (let i = 0; i < keyArray.length; i++) {
            tree.move(keyArray[i], e.target.key, targetIndex + i);
          }
        }
      }
    }  });

  return (
    <Tree
      aria-label="Tree with hierarchical drag and drop"
      selectionMode="multiple"
      items={tree.items}
      dragAndDropHooks={dragAndDropHooks}
    >
      {function renderItem(item) {
        return (
          <MyTreeItem title={item.value.title}>
            <Collection items={item.children}>
              {renderItem}
            </Collection>
          </MyTreeItem>
        );
      }}
    </Tree>
  );
}

function Example() {
  let tree = useTreeData({
    initialItems: items
  });

  let { dragAndDropHooks } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map((key) => ({
        'text/plain': tree.getItem(key).value.title
      })),
    onMove(e) {
      if (e.target.dropPosition === 'before') {
        tree.moveBefore(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'after') {
        tree.moveAfter(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'on') {
        // Move items to become children of the target
        let targetNode = tree.getItem(e.target.key);
        if (targetNode) {
          let targetIndex = targetNode.children
            ? targetNode.children.length
            : 0;
          let keyArray = Array.from(e.keys);
          for (let i = 0; i < keyArray.length; i++) {
            tree.move(
              keyArray[i],
              e.target.key,
              targetIndex + i
            );
          }
        }
      }
    }  });

  return (
    <Tree
      aria-label="Tree with hierarchical drag and drop"
      selectionMode="multiple"
      items={tree.items}
      dragAndDropHooks={dragAndDropHooks}
    >
      {function renderItem(item) {
        return (
          <MyTreeItem title={item.value.title}>
            <Collection items={item.children}>
              {renderItem}
            </Collection>
          </MyTreeItem>
        );
      }}
    </Tree>
  );
}

function Example() {
  let tree = useTreeData(
    {
      initialItems: items
    }
  );

  let {
    dragAndDropHooks
  } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map(
        (key) => ({
          'text/plain':
            tree.getItem(
              key
            ).value.title
        })
      ),
    onMove(e) {
      if (
        e.target
          .dropPosition ===
          'before'
      ) {
        tree.moveBefore(
          e.target.key,
          e.keys
        );
      } else if (
        e.target
          .dropPosition ===
          'after'
      ) {
        tree.moveAfter(
          e.target.key,
          e.keys
        );
      } else if (
        e.target
          .dropPosition ===
          'on'
      ) {
        // Move items to become children of the target
        let targetNode =
          tree.getItem(
            e.target.key
          );
        if (targetNode) {
          let targetIndex =
            targetNode
                .children
              ? targetNode
                .children
                .length
              : 0;
          let keyArray =
            Array.from(
              e.keys
            );
          for (
            let i = 0;
            i <
              keyArray
                .length;
            i++
          ) {
            tree.move(
              keyArray[
                i
              ],
              e.target
                .key,
              targetIndex +
                i
            );
          }
        }
      }
    }  });

  return (
    <Tree
      aria-label="Tree with hierarchical drag and drop"
      selectionMode="multiple"
      items={tree.items}
      dragAndDropHooks={dragAndDropHooks}
    >
      {function renderItem(
        item
      ) {
        return (
          <MyTreeItem
            title={item
              .value
              .title}
          >
            <Collection
              items={item
                .children}
            >
              {renderItem}
            </Collection>
          </MyTreeItem>
        );
      }}
    </Tree>
  );
}

Reordering within a level#

The onReorder event handler allows reordering items within the same level. Unlike onMove it does not allow moving items to a different level.

import {useTreeData} from 'react-stately';
import {Button, useDragAndDrop} from 'react-aria-components';

function Example() {
  let tree = useTreeData({
    initialItems: items
  });

  let { dragAndDropHooks } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map((key) => ({
        'text/plain': tree.getItem(key).value.title
      })),
    onReorder(e) {
      if (e.target.dropPosition === 'before') {
        tree.moveBefore(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'after') {
        tree.moveAfter(e.target.key, e.keys);
      }
    }
  });
  return (
    <Tree
      aria-label="Reorderable tree"
      selectionMode="multiple"
      items={tree.items}
      dragAndDropHooks={dragAndDropHooks}    >
      {function renderItem(item) {
        return (
          <MyTreeItem title={item.value.title}>
            <Collection items={item.children}>
              {renderItem}
            </Collection>
          </MyTreeItem>
        );
      }}
    </Tree>
  );
}

import {useTreeData} from 'react-stately';
import {
  Button,
  useDragAndDrop
} from 'react-aria-components';

function Example() {
  let tree = useTreeData({
    initialItems: items
  });

  let { dragAndDropHooks } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map((key) => ({
        'text/plain': tree.getItem(key).value.title
      })),
    onReorder(e) {
      if (e.target.dropPosition === 'before') {
        tree.moveBefore(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'after') {
        tree.moveAfter(e.target.key, e.keys);
      }
    }
  });
  return (
    <Tree
      aria-label="Reorderable tree"
      selectionMode="multiple"
      items={tree.items}
      dragAndDropHooks={dragAndDropHooks}    >
      {function renderItem(item) {
        return (
          <MyTreeItem title={item.value.title}>
            <Collection items={item.children}>
              {renderItem}
            </Collection>
          </MyTreeItem>
        );
      }}
    </Tree>
  );
}