# File Tree

An indented list of folders and files: a tree with arrow-key navigation whose folders open and close, and onSelect reports the chosen file or folder.

- Category: Core Elements
- Page: https://wunderui.com/components/file-tree
- Tier: Free

## Install

```bash
npx wunderui-cli add file-tree
```

## Import

```tsx
import { FileTree, FileTreeNode, FileTreeProps } from "@/components/wunderui/file-tree"
```

## Minimal usage

Then use it:

```tsx
import { FileTree, type FileTreeNode } from "@/components/ui/file-tree"

const tree: FileTreeNode[] = [
  {
    id: "src",
    name: "src",
    children: [
      { id: "app", name: "app.tsx" },
      { id: "index", name: "index.ts" },
    ],
  },
  { id: "package", name: "package.json" },
]

export function Files() {
  return <FileTree aria-label="Project files" data={tree} />
}
```

Expected result: You see a bordered panel with an open src folder holding two files, and package.json below it.

## Usage

```tsx
import { FileTree, type FileTreeNode } from "@/components/ui/file-tree"

const tree: FileTreeNode[] = [
  {
    id: "src",
    name: "src",
    children: [
      {
        id: "components",
        name: "components",
        children: [
          {
            id: "ui",
            name: "ui",
            children: [
              { id: "button", name: "button.tsx" },
              { id: "card", name: "card.tsx" },
            ],
          },
          { id: "header", name: "header.tsx" },
        ],
      },
      { id: "app", name: "app.tsx" },
    ],
  },
  { id: "package", name: "package.json" },
]

export function Example() {
  return <FileTree aria-label="Project files" data={tree} />
}
```

## When to use

### Use File Tree for

- The files of a template, an export or a repository, shown beside a preview
- A folder structure people browse with the keyboard
- A nested list with one chosen row, where the choice opens something else

### Use something else

- [Table](https://wunderui.com/components/table) for items people search, sort or select in bulk
- [Accordion](https://wunderui.com/components/accordion) for sections of text that open one at a time
- [Collapsible](https://wunderui.com/components/collapsible) for a single show-more panel

## Keyboard

The tree follows the WAI-ARIA tree pattern: one row is the tab stop, and the arrow keys move between the rows that are visible.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the tree on one row: the last focused one, else the selected one, else the first. The next press leaves the tree. |
| `↓` or `↑` | Moves focus to the next or previous visible row. Rows inside a closed folder are skipped. |
| `→` | On a closed folder, opens it. On an open folder, moves focus to its first child. On a file, nothing happens. |
| `←` | On an open folder, closes it. Otherwise moves focus to the parent folder. |
| `Home` or `End` | Moves focus to the first or the last visible row. |
| `Enter` or `Space` | Selects the focused row and calls `onSelect`. On a folder it also opens or closes it. |
| `A to Z` | Type-ahead: a letter moves focus to the next visible row whose name starts with it. One letter, no word search. |

## Behavior

What the tree does with state, content, focus and motion.

- **Selection:** One row is selected at a time, and choosing a folder selects and toggles it. Pass a selected id to control the selection, and update it in the select handler.
- **Initial state:** Top-level folders start open and deeper folders closed. After that the tree keeps its own open folders, and there is no prop to open one from outside.
- **Roving tab stop:** Only one row has the tab stop. If a collapse hides the focused row, the nearest visible parent takes it, so focus never lands inside a closed folder.
- **Closed folders are inert:** The rows of a closed folder stay in the DOM but are inert: they cannot be focused or clicked, and assistive technology skips them.
- **Empty folders:** A folder with an empty children list draws a chevron and opens to nothing. There is no empty row, so add a placeholder node if people should see that it is empty.
- **Long names:** A name that does not fit is cut with an ellipsis. Give the tree a width with a class name, since the panel is as wide as its parent by default.
- **Icons and metadata:** Folders show a folder icon and files a file icon. There is no slot for another icon, a badge or a size column.
- **Focus:** The focused row shows an indigo outline on the row only, not around the folder and its children.
- **Opening and closing:** Children slide and fade in and out. Opening takes the base duration with the entrance curve, closing is a step faster, and the chevron turns 90 degrees on the fast duration.
- **Reduced motion:** With reduced motion the children appear and disappear without sliding and the chevron does not turn. Hover and selected fills still change.

## Anatomy

- `FileTree`: A bordered panel that draws the data as rows, named Files by default. Top-level folders start open and deeper ones closed, and one row is the tab stop while the arrow keys move between visible rows.
- `Folder row`: A tree item with a chevron, a folder icon and the name. Choosing it opens or closes its children and selects it; Right opens it or enters the first child, Left closes it.
- `File row`: A tree item with a file icon and the name, cut with an ellipsis when too long. Choosing it selects it and calls your select handler, and the selected row has a subtle fill.
- `Children`: The nested rows, indented one step per level. While closed they are inert and the arrow keys skip them, so focus never lands inside a closed folder.

## Best practices

### When to use

- Use a File Tree to show a folder structure people look through, such as the files of a template or an export. For items people search, sort or select in bulk, use Table.

### Do

- Give every node a unique, stable id. It is the React key and the selection value, and a reused id mixes up which folders are open.
- Mark a folder with a children array, even an empty one. A node without children is drawn as a file.
- Keep the choice in your own state when something else on the page depends on it, such as an open file. Without it the tree keeps its own selection.
- Name the tree with an aria-label when the page has more than one, such as Project files. The default name is Files.

### Don't

- Don't use it for multiple selection, drag and drop, renaming or icons per file type. It selects one row at a time and draws the same two icons.
- Don't expect it to load children on demand. The tree draws the data it gets, so a folder that is still loading needs its own placeholder row.

## API reference

### FileTree

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | FileTreeNode[] |  | The nodes of the tree. A node is `{ id, name, children? }`: a node with a `children` array is a folder (empty or not), one without is a file. Ids must be unique. |
| aria-label | string |  | The accessible name of the tree. The default is `Files`; give each tree on a page its own name. |
| className | string |  | Extra classes for the panel, merged with its own. Use it for the width, or to drop the border and fill (`border-0 bg-transparent`) when the tree sits in a pane that has its own. |
| onSelect | (node: FileTreeNode) => void |  | Called with the node that was chosen by click, Enter or Space. A folder is reported too, as it is selected and toggled. |
| selectedId | string |  | The `id` of the selected row, for a controlled tree. Update it in `onSelect`. Without it the tree keeps its own selection. |

## Examples

### Structure: files, folders, nested rows, long names and an empty folder

```tsx
import { FileTree, type FileTreeNode } from "@/components/ui/file-tree"

const tree: FileTreeNode[] = [
  {
    id: "src",
    name: "src",
    children: [
      {
        id: "components",
        name: "components",
        children: [
          {
            id: "ui",
            name: "ui",
            children: [
              { id: "button", name: "button.tsx" },
              { id: "card", name: "card.tsx" },
            ],
          },
          { id: "header", name: "header.tsx" },
        ],
      },
      { id: "app", name: "app.tsx" },
    ],
  },
  { id: "package", name: "package.json" },
]

export function Example() {
  return <FileTree aria-label="Project files" data={tree} />
}
```

### States: default, file selected and folder selected

```tsx
import { FileTree, type FileTreeNode } from "@/components/ui/file-tree"

const tree: FileTreeNode[] = [
  {
    id: "src",
    name: "src",
    children: [
      { id: "app", name: "app.tsx" },
      { id: "index", name: "index.ts" },
    ],
  },
  {
    id: "public",
    name: "public",
    children: [
      { id: "logo", name: "logo.svg" },
    ],
  },
  { id: "package", name: "package.json" },
]

export function Example() {
  return <FileTree aria-label="Project files" data={tree} />
}
```

## In context

### Code explorer: the tree beside the open file

Choosing a file opens it in the pane. Choosing a folder only opens or closes it, so the open file keeps its row.

```tsx
import { useState } from "react"
import { FileTree, type FileTreeNode } from "@/components/ui/file-tree"

const tree: FileTreeNode[] = [
  {
    id: "src",
    name: "src",
    children: [
      {
        id: "components",
        name: "components",
        children: [
          { id: "button", name: "button.tsx" },
          { id: "card", name: "card.tsx" },
        ],
      },
      { id: "app", name: "app.tsx" },
    ],
  },
  { id: "package", name: "package.json" },
]

const files: Record<string, string> = {
  button: `export function Button({ children }) {
  return <button className="btn">{children}</button>
}`,
  card: `export function Card({ children }) {
  return <section className="card">{children}</section>
}`,
  app: `export function App() {
  return <Card>Hello</Card>
}`,
  package: `{
  "name": "wunderui-app",
  "version": "1.0.0"
}`,
}

const paths: Record<string, string> = {
  button: "src/components/button.tsx",
  card: "src/components/card.tsx",
  app: "src/app.tsx",
  package: "package.json",
}

export function Example() {
  const [fileId, setFileId] = useState("button")

  return (
    <div className="@container">
      <div className="flex flex-col overflow-hidden rounded-xl border border-border bg-card @md:h-56 @md:flex-row">
        <div className="shrink-0 border-b border-border p-2 @md:w-48 @md:border-r @md:border-b-0">
          <p className="px-2 pb-2 text-xs font-medium text-text-tertiary uppercase">Explorer</p>
          <FileTree
            aria-label="Project files"
            data={tree}
            selectedId={fileId}
            onSelect={(node) => {
              if (!node.children) setFileId(node.id)
            }}
            className="rounded-none border-0 bg-transparent p-0"
          />
        </div>
        <div className="flex min-w-0 flex-1 flex-col">
          <p className="truncate border-b border-border px-3 py-2 text-xs text-text-secondary">{paths[fileId]}</p>
          <pre className="min-h-24 flex-1 overflow-auto p-3 font-mono text-xs leading-5 text-text-secondary">
            {files[fileId]}
          </pre>
        </div>
      </div>
    </div>
  )
}
```

### File details: onSelect fills a panel

A select handler receives the chosen file or folder, and the panel beside the tree shows its name, type and path.

```tsx
import { useState } from "react"
import { FileTree, type FileTreeNode } from "@/components/ui/file-tree"

const tree: FileTreeNode[] = [
  {
    id: "brand",
    name: "Brand",
    children: [
      { id: "logo", name: "logo-mark.svg" },
      { id: "guide", name: "brand-guide.pdf" },
    ],
  },
  {
    id: "screens",
    name: "Screens",
    children: [
      {
        id: "auth",
        name: "auth",
        children: [
          { id: "signin", name: "sign-in.tsx" },
        ],
      },
      { id: "dashboard", name: "dashboard.tsx" },
    ],
  },
  { id: "tokens", name: "tokens.json" },
]

const paths: Record<string, string> = {
  brand: "Brand",
  logo: "Brand/logo-mark.svg",
  guide: "Brand/brand-guide.pdf",
  screens: "Screens",
  auth: "Screens/auth",
  signin: "Screens/auth/sign-in.tsx",
  dashboard: "Screens/dashboard.tsx",
  tokens: "tokens.json",
}

export function Example() {
  const [selected, setSelected] = useState<FileTreeNode>()

  return (
    <div className="@container">
      <div className="flex flex-col gap-3 @sm:flex-row">
        <FileTree
          aria-label="Design files"
          data={tree}
          selectedId={selected?.id}
          onSelect={setSelected}
          className="w-full @sm:w-56"
        />
        <div className="flex min-w-0 flex-1 flex-col gap-1 rounded-xl border border-border bg-card p-3 text-sm">
          <span className="text-text-tertiary">
            {selected ? (selected.children ? "Folder" : "File") : "Nothing selected"}
          </span>
          <span className="truncate font-medium text-foreground" aria-live="polite">
            {selected?.name ?? "Choose a file"}
          </span>
          <span className="truncate font-mono text-xs text-text-secondary">{selected ? paths[selected.id] : ""}</span>
        </div>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("file-tree")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
