TreeList·component·@astryxdesign/core

Tree List

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.

Open in Playground @astryxdesign/core/TreeList

Showcases and examples

6 documented examples

Tree List

TreeList API entry

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · tree-list-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {TreeList} from '@astryxdesign/core/TreeList';

const noop = () => {};

export default function TreeListShowcase() {
  return (
    <TreeList
      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

Provide meaningful labels and icons for each node to make the hierarchy easy to scan.
Pre-expand important branches so users see key content immediately.
Leaf rows reserve space for a chevron column whenever the tree has any expandable item to line up under; only a fully flat tree (no expandable items at all) renders its rows flush. Rely on this rather than nudging indentation with custom CSS.
Nest more than 4–5 levels deep; flatten the structure or use a different pattern.
Use a tree for flat, non-hierarchical data; use a List instead.

Typed props

Prop	Type and behavior
`items`	`TreeListItemData[]` · required Recursive tree item data with id, label, optional children and isExpanded, plus optional xstyle, className, and style applied to that item row.
`density`	`'compact' \| 'balanced' \| 'spacious'` · default 'balanced' Spacing density for items.
`variant`	`'lineGuides' \| 'noGuides'` · default 'lineGuides' Visual treatment of the hierarchy guide lines. lineGuides shows connector lines; noGuides hides them, keeping indentation. Orthogonal to density.
`header`	`ReactNode` Header content, associated with the tree via aria-labelledby. Slot: Text
`xstyle`	`StyleXStyles` StyleX styles for layout customization. Must be a stylex.create() value.

Anatomy

Tree list · required

Container that presents the hierarchical tree.

Header · optional

Caller-provided content that visibly names the tree.

Item · required

Painted row for one node in the hierarchy.

Chevron · optional

Expand and collapse control rendered for an Item with children.

Chevron glyph · optional

Directional symbol rendered by Icon inside a Chevron.

Item label · required

Primary content that identifies an Item.

Item description · optional

Secondary text rendered below an Item label.

Start content · optional

Caller-provided content rendered before an Item label.

End content · optional

Caller-provided content rendered after an Item label.

Guide · optional

Connector line that shows parent-child relationships.

Theming

Targets

astryx-tree-list

Visual props: density, variant

astryx-tree-list-item

Visual props: density

States: selected, disabled

astryx-tree-list-chevron

States: state

astryx-tree-list-item-label

States: selected

astryx-tree-list-guide

Variables

--tree-list-indent

Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the tree-list target to retune the metric (e.g. var(--spacing-5) for a wider indent).

Default: var(--spacing-4)

--tree-list-row-gap

Vertical gap between adjacent rows. Default 2px (var(--spacing-0-5)) gives a subtle separation; set it on the tree-list target to widen or close the gap. The connector guides span the gap automatically (the line stays continuous) and do not overhang the last row, so no guide-height tuning is needed.

Default: var(--spacing-0-5)

--_tree-indent · private

Distance one row is indented, computed per row from --tree-list-indent and the row depth. Set --tree-list-indent to retune indentation; this is the resolved value.

Default: 0px