XDS — Design System

XDSTreeList@xds/core · TreeList

Preview coming soon

Usage

An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.

Best practices

Guidance	Practices
Do	Provide meaningful labels and icons for each node to make the hierarchy easy to scan.
Do	Pre-expand important branches so users see key content immediately.
Don't	Nest more than 4–5 levels deep — flatten the structure or use a different pattern.
Don't	Use a tree for flat, non-hierarchical data — use a List instead.

Import

ts
import {XDSTreeList} from '@xds/core/TreeList'

Props

Prop	Type	Description
itemsrequired	XDSTreeListItemData[]	Recursive tree item data. Each item has id, label, optional children array, and optional isExpanded boolean for initial state.
density	'compact' \| 'balanced' \| 'spacious' (default: 'balanced')	Spacing density for items.
header	ReactNode	Header content, associated with the tree via aria-labelledby.
xstyle	StyleXStyles	StyleX styles for layout customization. Must be a stylex.create() value.

Sub-components

TreeList is a compound component with 1 sub-component.

XDSTreeList

Tree list container. Accepts items data and rendering configuration. Expansion state is managed internally.

Prop	Type	Description
itemsrequired	XDSTreeListItemData[]	Recursive tree item data. Each item has id, label, optional children array, and optional isExpanded boolean for initial state.
density	'compact' \| 'balanced' \| 'spacious' (default: 'balanced')	Spacing density for items.
header	ReactNode	Header content, associated with the tree via aria-labelledby.
xstyle	StyleXStyles	StyleX styles for layout customization. Must be a stylex.create() value.

Examples

Common configurations, variations, and states.

TreeList — File Tree With IconsFile browser tree with folder and document icons distinguishing directories from files.

tsx
'use client';
import {XDSTreeList} from '@xds/core/TreeList';
import {XDSIcon} from '@xds/core/Icon';
import {FolderIcon, DocumentIcon} from '@heroicons/react/24/outline';
export default function TreeListFileTreeWithIcons() {
  return (
    <XDSTreeList
      items={[
        {
          id: 'src',
          label: 'src',
          isExpanded: true,
          startContent: <XDSIcon icon={FolderIcon} size="sm" />,
          children: [
            {
              id: 'app',
              label: 'App.tsx',
              onClick: () => {},
              startContent: <XDSIcon icon={DocumentIcon} size="sm" />,
            },
            {
              id: 'index',
              label: 'index.tsx',
              onClick: () => {},
              startContent: <XDSIcon icon={DocumentIcon} size="sm" />,
            },
          ],
        },
        {
          id: 'pkg',
          label: 'package.json',
          onClick: () => {},
          startContent: <XDSIcon icon={DocumentIcon} size="sm" />,
        },
      ]}
    />
  );
}

TreeList — Interactive SettingsSettings tree with clickable items and a documentation link.

tsx
'use client';
import {XDSTreeList} from '@xds/core/TreeList';
import {XDSIcon} from '@xds/core/Icon';
import {Cog6ToothIcon, ChevronRightIcon} from '@heroicons/react/24/outline';
export default function TreeListInteractiveSettings() {
  return (
    <XDSTreeList
      items={[
        {
          id: 'settings',
          label: 'Settings',
          isExpanded: true,
          startContent: <XDSIcon icon={Cog6ToothIcon} size="sm" />,
          children: [
            {
              id: 'general',
              label: 'General',
              onClick: () => {},
            },
            {
              id: 'advanced',
              label: 'Advanced',
              onClick: () => {},
            },
          ],
        },
        {
          id: 'docs',
          label: 'Documentation',
          href: '#',
          endContent: <XDSIcon icon={ChevronRightIcon} size="sm" />,
        },
      ]}
    />
  );
}

TreeList — Mailbox TreeEmail folder tree with unread badge counts.

tsx
'use client';
import {XDSTreeList} from '@xds/core/TreeList';
import {XDSBadge} from '@xds/core/Badge';
const noop = () => {};
export default function TreeListMailboxTree() {
  return (
    <XDSTreeList
      items={[
        {
          id: 'inbox',
          label: 'Inbox',
          isExpanded: true,
          endContent: <XDSBadge label="3" />,
          children: [
            {
              id: 'unread',
              label: 'Unread',
              onClick: noop,
              endContent: <XDSBadge label="3" />,
            },
            {id: 'starred', label: 'Starred', onClick: noop},
          ],
        },
        {id: 'sent', label: 'Sent', onClick: noop},
        {
          id: 'drafts',
          label: 'Drafts',
          onClick: noop,
          endContent: <XDSBadge label="1" />,
        },
      ]}
    />
  );
}

TreeList — Navigation TreeNavigation tree with a selected item for the current page.

tsx
'use client';
import {XDSTreeList} from '@xds/core/TreeList';
const noop = () => {};
export default function TreeListNavigationTree() {
  return (
    <XDSTreeList
      items={[
        {
          id: 'nav',
          label: 'Navigation',
          isExpanded: true,
          children: [
            {id: 'home', label: 'Home', onClick: noop},
            {id: 'about', label: 'About', onClick: noop, isSelected: true},
            {id: 'contact', label: 'Contact', onClick: noop},
          ],
        },
      ]}
    />
  );
}

Showcase source

tsx
'use client';
import {XDSTreeList} from '@xds/core/TreeList';
const noop = () => {};
export default function TreeListShowcase() {
  return (
    <XDSTreeList
      items={[
        {
          id: 'src',
          label: 'src',
          isExpanded: true,
          children: [
            {
              id: 'components',
              label: 'components',
              children: [
                {id: 'button', label: 'Button.tsx', onClick: noop},
                {id: 'card', label: 'Card.tsx', onClick: noop},
                {id: 'list', label: 'List.tsx', onClick: noop},
              ],
            },
            {id: 'app', label: 'App.tsx', onClick: noop},
            {id: 'index', label: 'index.tsx', onClick: noop},
          ],
        },
        {
          id: 'public',
          label: 'public',
          children: [
            {id: 'favicon', label: 'favicon.ico', onClick: noop},
            {id: 'index-html', label: 'index.html', onClick: noop},
          ],
        },
        {id: 'pkg', label: 'package.json', onClick: noop},
        {id: 'readme', label: 'README.md', onClick: noop},
      ]}
    />
  );
}