A tree view presents a hierarchical list.

Usage

The TreeView component will handle the expand/collapse behaviour.

NOTE: It's important that we use React.useMemo (ref) when flattening our data to ensure that it isn't recreated on every render. Otherwise the component will behave unexpectedly.

Edit in Playroom

const data = [
  {
    name: 'Flavours',
    children: [{ name: 'Chocolate' }, { name: 'Vanilla' }, { name: 'Mint' }],
  },
  {
    name: 'Sizes',
    children: [{ name: 'Small' }, { name: 'Medium' }, { name: 'Large' }],
  },
];
const treeData = React.useMemo(() => flattenTreeData(data), []);
return (
  <TreeView
    label="Ice cream options"
    data={treeData}
    nodeRenderer={(node) => <Text>{node.name}</Text>}
  />
);

Selection

Use the onSelect and isSelected properties to manage node selection.

NOTE: The component uses the id property internally to track branches, so you must use another key to identify nodes. In this example we're using nodeID.

Edit in Playroom

const [selectedID, setSelectedID] = useState();
const data = [
  {
    name: 'Flavours',
    nodeID: 'flavour-0',
    children: [
      { name: 'Chocolate', nodeID: 'flavour-1' },
      { name: 'Vanilla', nodeID: 'flavour-2' },
      { name: 'Mint', nodeID: 'flavour-3' },
    ],
  },
  {
    name: 'Sizes',
    nodeID: 'size-0',
    children: [
      { name: 'Small', nodeID: 'size-1' },
      { name: 'Medium', nodeID: 'size-2' },
      { name: 'Large', nodeID: 'size-3' },
    ],
  },
];
const treeData = React.useMemo(() => flattenTreeData(data), []);
return (
  <Stack gap="small">
    <Text>
      Selected ID:{' '}
      <Text inline weight="bold">
        {selectedID ?? 'none'}
      </Text>
    </Text>
    <TreeView
      label="Selectable ice cream options"
      data={treeData}
      isSelected={(node) => selectedID === node.nodeID}
      onSelect={(node) => setSelectedID(node.nodeID)}
      nodeRenderer={(node) => <Text>{node.name}</Text>}
    />
  </Stack>
);

Rendering

Using the nodeRenderer compose Balance components to create the desired interface.

NOTE: It's important that we use React.useCallback (ref) when creating our nodeRenderer to ensure that it isn't recreated on every render. Otherwise you could see performance issues.

Edit in Playroom

const theme = useTheme();
const data = [
  {
    name: 'Reckmill Pty Ltd',
    children: [
      {
        name: 'External',
        children: [
          {
            name: 'Corportate',
            children: [{ name: 'Dashboard' }, { name: 'Widgets' }],
          },
          { name: 'Manufacturing' },
          { name: 'Retail' },
          { name: 'Trades' },
        ],
      },
      {
        name: 'Internal',
        children: [
          { name: 'Business' },
          { name: 'Clients' },
          { name: 'Users & Billing' },
        ],
      },
    ],
  },
  {
    name: 'Other',
  },
];
const treeData = React.useMemo(() => flattenTreeData(data), [data]);
// Create a component for the tree item
// ------------------------------------
// NOTE: should be declared **outside** of this component;
// This example is limited by the docs environment.
const TreeItem = ({ name }) => {
  return (
    <Inline gap="xsmall" alignY="center">
      <Inline flexGrow={1} gap="xsmall" alignY="center">
        <EntityAvatar name={name} type="Organisation" size="xsmall" />
        <Text size="small" weight="medium">
          {name}
        </Text>
      </Inline>
      <IconButton
        weight="subtle"
        label="Subtle"
        icon={FeatherIcon}
        size="small"
      />
    </Inline>
  );
};
// Then memoize the node renderer
const nodeRenderer = React.useCallback(
  (node) => <TreeItem name={node.name} />,
  []
);
return (
  <TreeView
    data={treeData}
    nodeRenderer={nodeRenderer}
    label="Company hierarchy"
  />
);

Tree View

Selection

Rendering