# React Native Tree View (Pro)

> A virtualized React Native tree view for iOS, Android and the web: expand and collapse with any icon, single selection or checkboxes with indeterminate parents, children loaded on demand, indent guides, WAI-ARIA keyboard navigation on the web and a design per platform. Part of Patine Pro, React Native core only.

# TreeView Pro

`TreeView` shows nested data: files and folders, categories, an org chart, permissions. Nodes open and close with a disclosure icon you can replace, select one at a time or check many (a parent checks all its children and shows a dash when only some are checked), and load their children from your server the first time they open. Rows are a flattened, virtualized `FlatList`, so a tree with thousands of nodes stays fast.

It's part of Patine Pro and uses React Native core only, like the free library. For a few nested sections, nest the free [Collapsible](../components/collapsible).

```tsx
import { TreeView } from '@patine-ui/pro';
```

```tsx live
import { Icon } from '@patine-ui/icons';
import { TreeView } from '@patine-ui/pro';

const FOLDER = <Icon name="folder" size="sm" />;
const FILE = <Icon name="fileText" size="sm" />;
const FILES = [
  {
    id: 'src',
    label: 'src',
    icon: FOLDER,
    children: [
      {
        id: 'components',
        label: 'components',
        icon: FOLDER,
        children: [
          { id: 'button', label: 'Button.tsx', icon: FILE },
          { id: 'card', label: 'Card.tsx', icon: FILE },
        ],
      },
      { id: 'index', label: 'index.ts', icon: FILE },
    ],
  },
  { id: 'docs', label: 'docs', icon: FOLDER, children: [{ id: 'intro', label: 'intro.mdx', icon: FILE }] },
  { id: 'readme', label: 'README.md', icon: FILE },
];

export default function Example() {
  return <TreeView data={FILES} defaultExpanded={['src']} accessibilityLabel="Files" style={{ height: 320, width: '100%', maxWidth: 360 }} />;
}
```

## Example: move a file to a folder

A shared drive's Move dialog: the tree shows the team's folders, one can be picked, and the button names where the file goes.

```tsx live
import { useState } from 'react';
import { Icon } from '@patine-ui/icons';
import { Button, Text, VStack } from 'patine-ui';
import { TreeView } from '@patine-ui/pro';

// A folder's id is its name here; use your API's ids.
type Folder = { id: string; label: string; icon: JSX.Element; children?: Folder[] };
const folder = (label: string, children: string[] = []): Folder => ({
  id: label,
  label,
  icon: <Icon name="folder" size="sm" />,
  children: children.length ? children.map((child) => folder(child)) : undefined,
});
const FOLDERS = [
  folder('Marketing', ['Campaigns 2026', 'Brand assets']),
  folder('Finance', ['Board meetings', 'Budgets', 'Payroll']),
  folder('Product', ['User research', 'Roadmap']),
];

export default function Example() {
  const [selected, setSelected] = useState<string[]>(['Board meetings']);
  const target = selected[0];
  return (
    <VStack gap="md" style={{ width: '100%', maxWidth: 360 }}>
      <VStack gap="xs">
        <Text weight="semibold">Move “Q4 board deck.key”</Text>
        <Text size="sm" color="textSecondary">Everyone with access to the folder will see it.</Text>
      </VStack>
      <TreeView
        data={FOLDERS}
        defaultExpanded={['Finance']}
        selected={selected}
        onSelectedChange={setSelected}
        accessibilityLabel="Folders"
        style={{ height: 260 }}
      />
      <Button disabled={!target}>{target ? `Move to ${target}` : 'Choose a folder'}</Button>
    </VStack>
  );
}
```

## Checkboxes

`selectionMode="multiple"` draws a checkbox on every row. Checking a parent checks everything under it; a parent with some children checked shows a dash (`'mixed'`). `selected` lists every checked id, parents included.

```tsx live
import { useState } from 'react';
import { Text, VStack } from 'patine-ui';
import { TreeView } from '@patine-ui/pro';

const PERMISSIONS = [
  {
    id: 'billing',
    label: 'Billing',
    children: [
      { id: 'billing.view', label: 'View invoices' },
      { id: 'billing.pay', label: 'Pay invoices' },
    ],
  },
  {
    id: 'team',
    label: 'Team',
    children: [
      { id: 'team.invite', label: 'Invite members' },
      { id: 'team.remove', label: 'Remove members', disabled: true },
    ],
  },
];

export default function Example() {
  const [selected, setSelected] = useState(['billing.view']);
  return (
    <VStack gap="sm" style={{ width: '100%', maxWidth: 360 }}>
      <TreeView
        data={PERMISSIONS}
        selectionMode="multiple"
        selected={selected}
        onSelectedChange={setSelected}
        defaultExpanded={['billing', 'team']}
        accessibilityLabel="Permissions"
        style={{ height: 260 }}
      />
      <Text size="sm" color="textSecondary">Checked: {selected.join(', ') || 'none'}</Text>
    </VStack>
  );
}
```

## Load children on demand

Mark a node `hasChildren` and pass `loadChildren`: the first time it opens, the row shows a spinner while your promise runs, then its children appear. Loaded children are kept.

```tsx live
import { TreeView } from '@patine-ui/pro';

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const ROOTS = [
  { id: 'eu', label: 'Europe', hasChildren: true },
  { id: 'asia', label: 'Asia', hasChildren: true },
];

async function loadChildren(node) {
  await wait(700);
  return [1, 2, 3].map((n) => ({ id: `${node.id}-${n}`, label: `${node.label} office ${n}`, hasChildren: n === 1 }));
}

export default function Example() {
  return <TreeView data={ROOTS} loadChildren={loadChildren} accessibilityLabel="Offices" style={{ height: 300, width: '100%', maxWidth: 360 }} />;
}
```

## Your own icons and labels

The disclosure icon takes the same props as [Collapsible](../components/collapsible#any-icon-anywhere): `icon`, `renderIcon={({ open }) => …}`, `iconPosition` (`'start'`, `'end'` or `'none'`) and `rotation`. Each node can have its own `icon` before the label, and `renderLabel(node, state)` draws the label from the node and its `expanded`, `selected`, `checked` and `level`.

```tsx live
import { Icon } from '@patine-ui/icons';
import { Badge, HStack, Text } from 'patine-ui';
import { TreeView } from '@patine-ui/pro';

const TEAMS = [
  {
    id: 'eng',
    label: 'Engineering',
    data: { count: 12 },
    children: [
      { id: 'web', label: 'Web', data: { count: 5 } },
      { id: 'mobile', label: 'Mobile', data: { count: 7 } },
    ],
  },
  { id: 'design', label: 'Design', data: { count: 4 } },
];

export default function Example() {
  return (
    <TreeView
      data={TEAMS}
      defaultExpanded={['eng']}
      renderIcon={({ open }) => <Icon name={open ? 'chevronDown' : 'chevronRight'} size="sm" color="primary" />}
      renderLabel={(node, state) => (
        <HStack justify="space-between">
          <Text weight={state.level === 0 ? 'medium' : 'regular'}>{node.label}</Text>
          <Badge variant="secondary">{String(node.data.count)}</Badge>
        </HStack>
      )}
      accessibilityLabel="Teams"
      style={{ height: 200, width: '100%', maxWidth: 360 }}
    />
  );
}
```

## Large trees

Only the visible rows are flattened and only those on screen render. Give the tree a height (or `flex: 1` in a sized parent) so it can scroll. Rows have a fixed height per design, which lets the list jump straight to any row; keep custom labels to one line.

## Designs

- **Brand** and **web**: an explorer like VS Code's, the disclosure arrow before the label and guides down each level.
- **iOS**: an outline like the Files sidebar, the chevron at the end and rounded selection.
- **Material**: Drive's tree, the selected row a pill with its label in the primary color.

`indentGuides` and `indent` override the design.

## Accessibility

- The list is a `tree` (multi-selectable with checkboxes); each row is a `treeitem` with its expanded, selected or checked (`mixed`) state, and on the web its level and place among its siblings.
- On the web, Tab reaches one row, and the arrow keys follow the WAI-ARIA tree pattern: up and down move, right opens a closed node or moves into an open one, left closes an open node or moves to its parent, Home and End jump to the ends. Enter presses the row, Space selects or checks it.
- Rows are at least 44pt tall; the disclosure icon has a wider touch area than it draws.
- The disclosure icon turns without animating with reduce motion on.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `TreeNode[]` | **required** | The roots. A node is `{ id, label, children?, hasChildren?, disabled?, icon?, data? }`. |
| `expanded` | `string[]` | — | Open node ids, controlled. |
| `defaultExpanded` | `string[]` | `[]` | Open node ids at first. |
| `onExpandedChange` | `(ids: string[]) => void` | — | Called when the user opens or closes a node. |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` | `'single'` | One selected node, checkboxes, or none. |
| `selected` | `string[]` | — | Selected (checked) ids, controlled. |
| `defaultSelected` | `string[]` | `[]` | Selected ids at first. |
| `onSelectedChange` | `(ids: string[]) => void` | — | Called when the user changes the selection. |
| `loadChildren` | `(node) => Promise<TreeNode[]>` | — | Loads a `hasChildren` node's children on first open. |
| `onNodePress` | `(node) => void` | — | Called when a row is pressed. |
| `expandOnPress` | `boolean` | `true`, `false` with checkboxes | Pressing a parent row also opens or closes it. |
| `renderLabel` | `(node, state) => ReactNode` | — | Draws a row's label. |
| `icon`, `renderIcon`, `iconPosition`, `rotation` | | the design's | The disclosure icon, as on [Collapsible](../components/collapsible#collapsibletrigger). |
| `indentGuides` | `boolean` | the design's | Lines down each level. |
| `indent` | `number` | the design's | Indent per level, in points. |
| `accessibilityLabel` | `string` | — | What a screen reader calls the tree. |
| `style`, `rowStyle`, `labelStyle` | styles | — | The list, each row, each label. |
| `theme`, `design` | | from `PatineProvider` | Theme override and design. |
