File Explorer

ProNew

A file tree with icons by type, in-place rename on F2 with validation, Delete handling and version control marks that are also spoken.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

When to use it

Use it for code editors, storage browsers, asset managers and anything that looks like a project folder.

Do not use it for read-only display of a structure (use the simpler file-tree), or for hierarchies that are not files.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/file-explorer

It uses tree-view, which the CLI installs for you.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode[]`	-	Folders have children; the rest are files.
`onOpen`	`(node) => void`	-	Enter or double click on a file.
`onRename`	`(node, name) => void`	-	Called with a valid new name. Without it F2 does nothing.
`onDelete`	`(node) => void`	-	The Delete key.
`statuses`	`Record<id, "modified" \| "added" \| "deleted" \| "ignored">`	-	Marks after the name.
`...`	-	-	All `TreeView` props.

Accessibility

The rename field is named New name for {file}; an invalid name sets aria-invalid and shows a role=alert message linked with aria-describedby.
A name must be non-empty, contain no slash and be unique in its folder (ignoring case).
Status marks (M, A, D, I) are decorative; the row's name adds ", modified" for screen readers.

Keyboard

F2: rename the focused row. Enter saves, Escape cancels, focus returns to the row.
Delete: calls onDelete (you ask for confirmation).
Enter on a file: onOpen; on a folder: open or close.
All the tree keys from tree-view.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

fileIconFor(name) and validateFileName(nodes, id, name) are exported.

Testing

The component ships with a Testing Library test (file-explorer.test.tsx) that covers its keyboard paths, roles and states.

Guide and examples

When to use it

Use it for code editors, storage browsers, asset managers and anything that looks like a project folder.

Do not use it for read-only display of a structure (use the simpler file-tree), or for hierarchies that are not files.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/file-explorer

It uses tree-view, which the CLI installs for you.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode[]`	-	Folders have children; the rest are files.
`onOpen`	`(node) => void`	-	Enter or double click on a file.
`onRename`	`(node, name) => void`	-	Called with a valid new name. Without it F2 does nothing.
`onDelete`	`(node) => void`	-	The Delete key.
`statuses`	`Record<id, "modified" \| "added" \| "deleted" \| "ignored">`	-	Marks after the name.
`...`	-	-	All `TreeView` props.

Accessibility

The rename field is named New name for {file}; an invalid name sets aria-invalid and shows a role=alert message linked with aria-describedby.
A name must be non-empty, contain no slash and be unique in its folder (ignoring case).
Status marks (M, A, D, I) are decorative; the row's name adds ", modified" for screen readers.

Keyboard

F2: rename the focused row. Enter saves, Escape cancels, focus returns to the row.
Delete: calls onDelete (you ask for confirmation).
Enter on a file: onOpen; on a folder: open or close.
All the tree keys from tree-view.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

fileIconFor(name) and validateFileName(nodes, id, name) are exported.

Testing

The component ships with a Testing Library test (file-explorer.test.tsx) that covers its keyboard paths, roles and states.