Configure Tree data format and mapping

Choose between flat and hierarchy dataFormat, and map fields with idField, nameField, parentIdField, and more.

Tree supports two data shapes: flat arrays where each node references its parent by ID, and nested arrays where each node carries its children inline. Set dataFormat to choose the shape, then use field-mapping props to adapt any API response without transforming the data first.

<App>
  <HStack gap="$space-6" alignItems="flex-start">
    <VStack flex="1">
      <Text variant="strong">Flat format</Text>
      <Text variant="secondary" size="sm">Each node references its parent by ID</Text>
      <Tree
        dataFormat="flat"
        idField="id"
        nameField="name"
        parentIdField="parentId"
        defaultExpanded="all"
        data="{[
          { id: 1, name: 'Electronics', parentId: null },
          { id: 2, name: 'Phones', parentId: 1 },
          { id: 3, name: 'Laptops', parentId: 1 },
          { id: 4, name: 'iPhone', parentId: 2 },
          { id: 5, name: 'Pixel', parentId: 2 }
        ]}"
      />
    </VStack>
    <VStack flex="1">
      <Text variant="strong">Hierarchy format</Text>
      <Text variant="secondary" size="sm">Each node embeds its children inline</Text>
      <Tree
        dataFormat="hierarchy"
        idField="key"
        nameField="title"
        childrenField="items"
        defaultExpanded="all"
        data="{[
          { key: 1, title: 'Electronics', items: [
              { key: 2, title: 'Phones', items: [
                  { key: 4, title: 'iPhone', items: [] },
                  { key: 5, title: 'Pixel', items: [] }
              ]},
              { key: 3, title: 'Laptops', items: [] }
          ]}
        ]}"
      />
    </VStack>
  </HStack>
</App>
Tree flat vs hierarchy data format
<App>
  <HStack gap="$space-6" alignItems="flex-start">
    <VStack flex="1">
      <Text variant="strong">Flat format</Text>
      <Text variant="secondary" size="sm">Each node references its parent by ID</Text>
      <Tree
        dataFormat="flat"
        idField="id"
        nameField="name"
        parentIdField="parentId"
        defaultExpanded="all"
        data="{[
          { id: 1, name: 'Electronics', parentId: null },
          { id: 2, name: 'Phones', parentId: 1 },
          { id: 3, name: 'Laptops', parentId: 1 },
          { id: 4, name: 'iPhone', parentId: 2 },
          { id: 5, name: 'Pixel', parentId: 2 }
        ]}"
      />
    </VStack>
    <VStack flex="1">
      <Text variant="strong">Hierarchy format</Text>
      <Text variant="secondary" size="sm">Each node embeds its children inline</Text>
      <Tree
        dataFormat="hierarchy"
        idField="key"
        nameField="title"
        childrenField="items"
        defaultExpanded="all"
        data="{[
          { key: 1, title: 'Electronics', items: [
              { key: 2, title: 'Phones', items: [
                  { key: 4, title: 'iPhone', items: [] },
                  { key: 5, title: 'Pixel', items: [] }
              ]},
              { key: 3, title: 'Laptops', items: [] }
          ]}
        ]}"
      />
    </VStack>
  </HStack>
</App>

Key points

dataFormat="flat" uses parent references: Each node is an object in a flat array that references its parent via a field (default: parentId). Nodes without a parent ID (or with null) become root items. Use parentIdField to remap to any field name your API returns, such as "parent_id" or "pid".

dataFormat="hierarchy" uses nested child arrays: Each node embeds its children inline under a field (default: "children"). Use childrenField to remap to any field name your API returns, such as "items" or "nodes". parentIdField is unused in this mode.

idField and nameField apply to both formats: idField (default "id") is required for selection, expansion state, and async loading. nameField (default "name") is the display text. Map these to whatever your API returns.

defaultExpanded controls initial open state: Accepted values are "none" (all collapsed), "all" (everything open), "first-level" (only root children visible), or an array of IDs for selective expansion. autoExpandToSelection (default true) automatically opens the path to a pre-selected node.

iconField, selectableField, and friends are also remappable: Per-node icon names come from iconField (default "icon"). Node-level selectability is read from selectableField (default "selectable"). For async trees, dynamicField marks nodes that can load children on demand.

See also