File Tree
FreeShow a folder structure that people look through, with folders that open and close and one chosen row.
npx wunderui-cli add file-treePlayground
Installation
npx wunderui-cli add file-treeWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { FileTree } from "@/components/wunderui/file-tree"
import type {
FileTreeNode,
FileTreeProps,
} from "@/components/wunderui/file-tree"Then use it:
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.
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 for
- Table for items people search, sort or select in bulk
- Accordion for sections of text that open one at a time
- Collapsible for a single show-more panel
Structure
A node with children is a folder, one without is a file. Top-level folders start open, deeper ones closed, and a name that does not fit is cut with an ellipsis.
States
One row is chosen at a time, a file or a folder. Click it, or focus it and press Enter, and pass a selected id to keep the choice in your own state.
Keyboard interactions
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.
- TaborShift+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.
- HomeorEnd
- Moves focus to the first or the last visible row.
- EnterorSpace
- Selects the focused row and calls . 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 and motion
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
The parts a tree is made of, numbered in the figure. The tree and its rows are plain elements with ARIA roles, so they have no data-slot to target.
- 1
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.
- 2Optional
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.
- 4Optional
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.
- 3Optional
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.
Best practices
- 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.
- Do
Mark a folder with a children array, even an empty one. A node without children is drawn as a file.
- Do
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.
- Do
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
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 draws one panel and takes the props below. A node has an id, a name and optional children.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| data required | FileTreeNode[] | — | The nodes of the tree. A node is : a node with a 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 ; give each tree on a page its own name. |
| selectedId | string | — | The of the selected row, for a controlled tree. Update it in . Without it the tree keeps its own selection. |
| onSelect | (node) => void | — | Called with the node that was chosen by click, Enter or Space. A folder is reported too, as it is selected and toggled. |
| className | string | — | Extra classes for the panel, merged with its own. Use it for the width, or to drop the border and fill () when the tree sits in a pane that has its own. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("file-tree")npx wunderui-cli add file-treeThe full library index for assistants is at /llms.txt.
Related components
Recent invoicesInvoices issued in the last 30 days Invoice Status Customer Amount INV-2041 Paid WunderUI $24,800.00 INV-2040 Open Halcyon Labs $3,200.00 INV-2039 Overdue Pergola Foods $980.00 INV-2038 Paid Marlow & Finch $12,400.00 Total Sum$41,380.00 Core Elements5 stylesTableRows and columns with 23 ready-made cell types; for sorting and search use Data Table.