XDS — Design System

TreeList@xds/core · XDSTreeList v0.0.13

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.

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

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.

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},
      ]}
    />
  );
}

Usage

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

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.

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.

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" />, }, ]} /> ); }

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" />, }, ]} /> ); }

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" />, }, ]} /> ); }

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}, ], }, ]} /> ); }

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}, ]} /> ); }