TreeList

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.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

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.

Usage guidance

• 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.
• Avoid: Nest more than 4–5 levels deep; flatten the structure or use a different pattern.
• Avoid: Use a tree for flat, non-hierarchical data; use a List instead.

Theming API

{
  "targets": [
    {
      "className": "astryx-tree-list",
      "visualProps": [
        "density",
        "variant"
      ]
    },
    {
      "className": "astryx-tree-list-item",
      "visualProps": [
        "density"
      ],
      "states": [
        "selected",
        "disabled"
      ]
    },
    {
      "className": "astryx-tree-list-chevron",
      "states": [
        "state"
      ]
    },
    {
      "className": "astryx-tree-list-item-label",
      "states": [
        "selected"
      ]
    },
    {
      "className": "astryx-tree-list-guide"
    }
  ],
  "vars": [
    {
      "name": "--tree-list-indent",
      "description": "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)"
    },
    {
      "name": "--tree-list-row-gap",
      "description": "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)"
    },
    {
      "name": "--_tree-indent",
      "description": "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",
      "private": true
    }
  ]
}

Tree List

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

Anatomy

• Tree list: Container that presents the hierarchical tree.
• Header: Caller-provided content that visibly names the tree.
• Item: Painted row for one node in the hierarchy.
• Chevron: Expand and collapse control rendered for an Item with children.
• Chevron glyph: Directional symbol rendered by Icon inside a Chevron.
• Item label: Primary content that identifies an Item.
• Item description: Secondary text rendered below an Item label.
• Start content: Caller-provided content rendered before an Item label.
• End content: Caller-provided content rendered after an Item label.
• Guide: Connector line that shows parent-child relationships.

Examples

• Tree List:
• TreeList — File Tree With Icons: File browser tree with folder and document icons distinguishing directories from files.
• TreeList — Interactive Settings: Settings tree with clickable items and a documentation link.
• TreeList — Mailbox Tree: Email folder tree with unread badge counts.
• TreeList — Navigation Tree: Navigation tree with a selected item for the current page.
• Tree List — Variants: The variant prop controls whether hierarchy guide lines are shown: lineGuides (default) draws connector lines between parent and child rows, while noGuides relies on indentation alone. It is orthogonal to density, which controls spacing.

Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

npm install @heroicons/react@2.2.0