File Tree

Collapsible project tree with animated folders, file-type icons, and hover highlights.

Installation

npx shadcn@latest add @iconiq/file-tree

Props

FileTree

8 props

Root provider for the compound file tree. Tracks expanded folders, hover highlight bounds, and shared visual settings.

defaultExpandedIdsstring[]

Default[]

Folder node ids that should start expanded on first render.

highlightColorstring

Default#3b82f6

Text color applied to items with `highlight` on `FileTreeItem`.

indentSizenumber

Default24

Horizontal indent in pixels for each nested folder level.

showIconsboolean

Defaulttrue

Whether to render icons. File icons are inferred from the label extension when no custom icon is provided.

onNodeClick(nodeId: string) => void

Called when a file or folder row is activated.

onNodeExpand(nodeId: string, expanded: boolean) => void

Called when a folder branch opens or closes.

classNamestring

Optional class names applied to the bordered root container.

childrenReact.ReactNode

Usually a single `FileTreeList` with nested `FileTreeItem` rows.

Notes

Wrap `FileTreeList` and nested `FileTreeItem` components inside the root provider.

Hovering any row updates a single animated highlight that follows the active item inside the tree container.

FileTreeList

2 props

Semantic tree container for top-level and nested file rows. Supports Base UI `render` composition instead of Radix Slot.

classNamestring

Merged with the default vertical stack layout.

renderReactElement | ((props) => ReactElement)

Optional Base UI render override for the list container element.

FileTreeItem

6 props

Single file or folder row. Nested children render as an animated branch when the row is expandable.

nodeIdstring

Required

Stable unique id used for expand state, callbacks, and tree semantics.

labelstring

Required

Display label for the row. File extension is used to pick a default icon.

iconReact.ReactNode

Optional custom icon node rendered before the label.

hasChildrenboolean

Marks the row as a branch even when it has no nested children yet. Otherwise inferred from child items.

highlightboolean

When true, tints the row with `highlightColor` to mark it as new or relevant.

childrenReact.ReactNode

Nested `FileTreeItem` rows rendered when the branch is expanded.

Notes

Folder rows use Base UI Button for the toggle control while file rows remain static display rows.

Folder icons swap with a spring transition, and child lists animate open and closed with height and opacity motion.