# File Tree (/docs/agent-ui/components/file-tree)

Use a file tree beside a diff or a summary of what the agent edited, so readers can see which files changed and how much. Each file shows its change as a letter and the lines it added and removed; a folder shows a dot in the color of the most significant change inside it.

<Example caption="Press a folder, or focus a row and press the Right and Left arrow keys, to open and close it. Up and Down move between rows, and typing a name moves to it.">
<h />

```tsx
import { FileTree } from "@/components/ui/file-tree";

const entries = [
  { path: "src/index.ts", change: "modified" as const, additions: 12, deletions: 3 },
  { path: "src/lib/format.ts", change: "added" as const, additions: 40 },
  { path: "src/lib/parse.ts" },
  { path: "src/routes/old.tsx", change: "deleted" as const, deletions: 18 },
  { path: "src/routes/home.tsx", change: "renamed" as const },
  { path: "package.json", change: "modified" as const, additions: 1, deletions: 1 },
  { path: "README.md" },
];

export default function FileTreeExample() {
  return <FileTree entries={entries} defaultExpanded={["src", "src/lib"]} className="w-full max-w-sm" />;
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/file-tree
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/file-tree-web
```

## Composition [#composition]

```text
FileTree
└── FileTreeItem
    ├── FileTreeCounts
    └── FileTreeBadge
```

`FileTree` renders a UI SDK Tree with a row for each folder and file. `FileTreeItem` is a row's icon and name. `FileTreeCounts` shows the lines a file added and removed as `+N −N`, and `FileTreeBadge` its change as `A`, `M`, `D` or `R`. Screen readers hear both as words, like "index.ts 12 additions, 3 deletions modified".

## Usage [#usage]

### Entries [#entries]

Pass `entries`, each with a relative `path` like `src/index.ts`, and optionally a `change` (`"added"`, `"modified"`, `"deleted"` or `"renamed"`), `additions` and `deletions`. Folders come from the paths and sort before files, in the order they first appear. A path ending in `/` is an empty folder. A deleted file's name is struck through.

```tsx
<FileTree
  entries={[
    { path: "src/index.ts", change: "modified", additions: 12, deletions: 3 },
    { path: "src/cache.ts", change: "added", additions: 7 },
    { path: "README.md" },
  ]}
/>
```

### Updating Entries [#updating-entries]

Pass new `entries` as the change grows. Open folders stay open, and the focused row keeps focus; when the focused file goes away, focus moves to a row beside it. A file added after the first render fades in once. Folders slide open and closed; under `prefers-reduced-motion`, or with `motion="reduced"`, they fade over 120 ms, and with `motion="none"` they switch at once.

### Selecting Files [#selecting-files]

Pressing a row, or Enter or Space on it, selects it. Pass `onSelect` to open a file: it gets the file's path when a person presses it or presses Enter on it. Folders open and close instead. Pass `defaultValue`, or `value` with `onValueChange`, for the selected path, and `defaultExpanded`, or `expanded` with `onExpandedChange`, for the open folders, by path without a trailing `/`.

```tsx
<FileTree entries={entries} onSelect={(path) => openFile(path)} />
```

### Keyboard [#keyboard]

The tree is one Tab stop. Up and Down move between the rows that show, Home and End go to the first and last, Right opens a folder or moves into it, and Left closes it or moves to its folder. Typing moves to the next row whose name starts with what you typed. Closed folders stay in the page, so the browser's find in page reaches the files inside and opens their folders.

## API Reference [#api-reference]

### FileTreeOptions

| Prop                | Type                                                                                                | Description                                                                                                                                                                                    |
| ------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entries?`          | `FileTreeEntry[] \| undefined`                                                                      | The files, by relative path like `src/index.ts`, each with how the change touched it. Folders come from the paths, sorted before files; a path ending in `/` is an empty folder. Default: `[]` |
| `label?`            | `string \| undefined`                                                                               | Names the tree. Default: `"Files"`                                                                                                                                                             |
| `value?`            | `string \| null \| undefined`                                                                       | The selected path. Passing it controls it: change it in `onValueChange`.                                                                                                                       |
| `defaultValue?`     | `string \| null \| undefined`                                                                       | The selected path at first, when `value` isn't passed. Default: `null`                                                                                                                         |
| `onValueChange?`    | `((value: string \| null, details: ChangeDetails<FileTreeValueChangeReason>) => void) \| undefined` | Called when a person or `select` selects a file or folder, with why.                                                                                                                           |
| `expanded?`         | `string[] \| undefined`                                                                             | The open folders' paths, without a trailing `/`. Passing it controls them: change them in `onExpandedChange`.                                                                                  |
| `defaultExpanded?`  | `string[] \| undefined`                                                                             | The open folders at first, when `expanded` isn't passed. Default: `[]`                                                                                                                         |
| `onExpandedChange?` | `((expanded: string[], details: ChangeDetails<FileTreeExpandedChangeReason>) => void) \| undefined` | Called when folders open or close, with why.                                                                                                                                                   |
| `onSelect?`         | `((path: string, details: ChangeDetails<FileTreeSelectReason>) => void) \| undefined`               | Called with a file's path when a person presses it or presses Enter on it, or an agent selects it, once the selection moved to it; not when `onValueChange` refused that.                      |
| `motion?`           | `"auto" \| "none" \| "reduced"`                                                                     | How folders open and close, and how files added after the first frame come in. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                    |

### Agent [#agent]

An agent connected with `createAgent` finds the tree by its `label`, "Files" by default, and reads `value` and `expanded`. It can name any folder or file by path. `expand(path)` opens a folder and the folders it's in, and `collapse(path)` closes one; both return `false` for a file. `select(path)` selects a file and calls `onSelect`, and is offered only while `onSelect` is set.

### FileTreeAgentActions

| Prop       | Type                                       | Description                                                                                                                                                                 |
| ---------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | `(path: string) => boolean`                | Opens a folder and the folders it's in. Returns `false` for a file or an unknown path, or a refused change.                                                                 |
| `collapse` | `(path: string) => boolean`                | Closes a folder. Returns `false` for a file or an unknown path, or a refused change.                                                                                        |
| `select`   | `((path: string) => boolean) \| undefined` | Selects a file and calls `onSelect`, as Enter on it would. Returns `false` for a folder or an unknown path, or when the host cancels. Offered only while `onSelect` is set. |

<Caption>
Runs in React and Web Components. On `<kind-file-tree>`, set `entries`, `defaultExpanded` and `expanded` as properties; the other props are kebab-case attributes. `onValueChange` is the `pathchange` event and `onExpandedChange` is `expandchange`. Add `can-select` to fire `fileselect` when a file is pressed.
</Caption>