# TreeList

- Page: https://jiguang132.com/resources/astryx/docs/tree-list
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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.

| Prop | Type | Default | Description |
|---|---|---|---|
| items * | TreeListItemData[] |  | 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' | 'balanced' | Spacing density for items. |
| variant | 'lineGuides' \| 'noGuides' | '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. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization. Must be a stylex.create() value. |

### 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:

```bash
npm install @heroicons/react@2.2.0
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt