# FileTree

> A TreeView preset for folders and files, with open and closed folder icons.

Category: Navigation · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/file-tree

Use FileTree to browse uploaded assets, exported templates or any folder structure. It is a TreeView with folder and file icons chosen by extension, so it shares the same keyboard model, selection and props. Pass getFileIcon to customise file icons.

## Import

```tsx
import { FileTree } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { FileTree } from '@bindshq/stance-react';
import type { TreeItem } from '@bindshq/stance-react';

const files: TreeItem[] = [
  {
    id: 'brand',
    label: 'brand-assets',
    children: [
      {
        id: 'logos',
        label: 'logos',
        children: [
          { id: 'logo-dark', label: 'binds-wordmark-dark.svg' },
          { id: 'logo-light', label: 'binds-wordmark-light.svg' },
        ],
      },
      { id: 'guide', label: 'brand-guidelines.pdf' },
    ],
  },
  {
    id: 'signatures',
    label: 'signatures',
    children: [
      { id: 'sales-html', label: 'sales.html' },
      { id: 'support-html', label: 'support.html' },
      { id: 'users-csv', label: 'org-users.csv' },
    ],
  },
  { id: 'readme', label: 'README.md' },
];

export function Basic() {
  return <FileTree items={files} defaultExpanded={['brand', 'logos']} style={{ width: 300 }} />;
}
```

### Opening files

onAction fires on Enter or click.

```tsx
import { FileTree } from '@bindshq/stance-react';
import type { TreeItem } from '@bindshq/stance-react';

const files: TreeItem[] = [
  {
    id: 'brand',
    label: 'brand-assets',
    children: [
      {
        id: 'logos',
        label: 'logos',
        children: [
          { id: 'logo-dark', label: 'binds-wordmark-dark.svg' },
          { id: 'logo-light', label: 'binds-wordmark-light.svg' },
        ],
      },
      { id: 'guide', label: 'brand-guidelines.pdf' },
    ],
  },
  {
    id: 'signatures',
    label: 'signatures',
    children: [
      { id: 'sales-html', label: 'sales.html' },
      { id: 'support-html', label: 'support.html' },
      { id: 'users-csv', label: 'org-users.csv' },
    ],
  },
  { id: 'readme', label: 'README.md' },
];

export function OpenOnAction() {
  return (
    <FileTree
      items={files}
      defaultExpanded={['signatures']}
      onAction={(item) => {
        if (!item.children) window.alert(`Opening ${item.label}`);
      }}
      style={{ width: 300 }}
    />
  );
}
```

### Custom file icons

```tsx
import { FileTree } from '@bindshq/stance-react';
import type { TreeItem } from '@bindshq/stance-react';

const files: TreeItem[] = [
  {
    id: 'brand',
    label: 'brand-assets',
    children: [
      {
        id: 'logos',
        label: 'logos',
        children: [
          { id: 'logo-dark', label: 'binds-wordmark-dark.svg' },
          { id: 'logo-light', label: 'binds-wordmark-light.svg' },
        ],
      },
      { id: 'guide', label: 'brand-guidelines.pdf' },
    ],
  },
  {
    id: 'signatures',
    label: 'signatures',
    children: [
      { id: 'sales-html', label: 'sales.html' },
      { id: 'support-html', label: 'support.html' },
      { id: 'users-csv', label: 'org-users.csv' },
    ],
  },
  { id: 'readme', label: 'README.md' },
];

export function CustomIcons() {
  return (
    <FileTree
      items={files}
      defaultExpanded={['signatures']}
      getFileIcon={(item) =>
        item.label.endsWith('.csv') ? 'users' : item.label.endsWith('.html') ? 'mail' : 'file'
      }
      style={{ width: 300 }}
    />
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| FileTree | `items` (required) | `TreeItem[]` | None | Folders are items with children. |
| FileTree | `aria-label` | `string` | `'Files'` | Name of the tree. |
| FileTree | `getFileIcon` | `(item: TreeItem) => IconName` | None | Icon for each file; defaults to an extension-based icon. |
| FileTree | `...TreeViewProps` | `TreeViewProps` | None | selectionMode, selected, expanded, onAction, size and every other TreeView prop. |

## Accessibility

- Inherits TreeView semantics: tree, treeitem and group roles with levels, positions, expansion and selection state.
- Folder state is conveyed by aria-expanded, not only by the open-folder icon.
- Icons are decorative and hidden from assistive technology.

## Keyboard

| Keys | Action |
| --- | --- |
| `↑` `↓` | Move between visible items. |
| `→` `←` | Open / close folders and move between parent and child. |
| `Enter` | Open the file (onAction). |
| `a to z` | Jump to an item by name. |

## Guidelines

**Do**

- Sort folders before files.
- Show full file names, including extensions.

**Don’t**

- Use FileTree for non-file hierarchies; use TreeView.

## Related

- https://stanceui.com/components/tree-view
- https://stanceui.com/components/file-upload