Skip to content
WunderUI

File Tree

Free

Show a folder structure that people look through, with folders that open and close and one chosen row.

npx wunderui-cli add file-tree

Playground

src
app.tsx
package.json

Installation

bash
npx wunderui-cli add file-tree

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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.

README.md
package.json
tsconfig.json
LICENSE

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.

src
app.tsx
index.ts
public
logo.svg
package.json

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.

TaborShiftTab
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.

src
app.tsx
package.json
  • 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.

  • Optional

    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.

  • Optional

    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.

  • Optional

    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.

PropTypeDefaultDescription
data requiredFileTreeNode[]—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-labelstring—The accessible name of the tree. The default is ; give each tree on a page its own name.
selectedIdstring—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.
classNamestring—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.

MCPget_component("file-tree")
Installnpx wunderui-cli add file-tree

The full library index for assistants is at /llms.txt.