File Tree
Collapsible folder and file tree with indent guides, file type icons and one open file, plus an optional path line. Use it for code browsers and docs sidebars.
How it differs. Baseline single-select tree: indent guides that darken beside the open file, a dot on a closed folder that holds it, and the full APG keyboard map with typeahead and asterisk.
Install
pnpm dlx shadcn@latest add @hazine/tree-view-file-explorerAdds 1 file, 1 Hazine item (@hazine/use-controllable-state), and 1 package (lucide-react).
First time? Add the registry to components.json
{
"registries": {
"@hazine": "https://api.hazine.dev/r/{name}.json"
}
}Needed once per project. Items resolve each other through the @hazine namespace.
The demo in the preview, 266 lines
"use client"
import * as React from "react"
import { ChevronsDownUp, ChevronsUpDown, Download } from "lucide-react"
import { Button } from "@/components/ui/button"
import {
TreeViewFileExplorer,
type FileTreeNode,
} from "@/components/hazine/tree-view-file-explorer"
const MICRO_LABEL =
"px-2 font-mono text-xs font-medium uppercase tracking-wider text-muted-foreground"
function file(path: string, disabled?: boolean): FileTreeNode {
return { id: path, name: path.slice(path.lastIndexOf("/") + 1), disabled }
}
function folder(
path: string,
children: FileTreeNode[],
disabled?: boolean
): FileTreeNode {
return { ...file(path, disabled), children }
}
export default function TreeViewFileExplorerDemo() {
return (
<div className="grid w-xs max-w-full gap-2">
<p className={MICRO_LABEL}>Ledgerline portal</p>
<TreeViewFileExplorer
label="Ledgerline portal files"
defaultValue="app/invoices/columns.tsx"
showPath
/>
</div>
)
}
const WORKSPACE_NODES: FileTreeNode[] = [
folder("src", [
folder("src/routes", [
file("src/routes/payouts.tsx"),
file("src/routes/refunds.tsx"),
]),
file("src/main.tsx"),
]),
folder("dist", [file("dist/index.js")], true),
folder("drafts", []),
file(".env.production", true),
file("package.json"),
]
function TreeViewFileExplorerCollapsedSelection() {
return (
<div className="grid w-xs max-w-full gap-2">
<p className={MICRO_LABEL}>Payouts service</p>
<TreeViewFileExplorer
label="Payouts service files"
nodes={WORKSPACE_NODES}
defaultExpanded={[]}
defaultValue="src/routes/refunds.tsx"
showPath
/>
<p className="px-2 text-xs text-muted-foreground">
The dot marks the closed folder that holds the open file.
</p>
</div>
)
}
function TreeViewFileExplorerDisabled() {
return (
<div className="grid w-xs max-w-full gap-2">
<p className={MICRO_LABEL}>Payouts service</p>
<TreeViewFileExplorer
label="Payouts service files"
nodes={WORKSPACE_NODES}
defaultExpanded={["src", "src/routes"]}
defaultValue="src/routes/payouts.tsx"
/>
<p className="px-2 text-xs text-muted-foreground">
Build output and production secrets are locked for the Viewer role.
</p>
</div>
)
}
// The locked entries stay out, so every folder here can be opened and the count adds up.
const EDITABLE_NODES = WORKSPACE_NODES.filter((node) => !node.disabled)
const ALL_FOLDERS = ["src", "src/routes", "drafts"]
function TreeViewFileExplorerControlled() {
const [open, setOpen] = React.useState<string | null>("src/main.tsx")
const [expanded, setExpanded] = React.useState(["src"])
// A folder counts as open only when every folder above it is open too.
const openCount = ALL_FOLDERS.filter((id) =>
id
.split("/")
.every((_, index, parts) =>
expanded.includes(parts.slice(0, index + 1).join("/"))
)
).length
return (
<div className="grid w-xs max-w-full gap-2">
<div className="flex items-center justify-between gap-2">
<p className={MICRO_LABEL}>Payouts service</p>
<div className="flex gap-1">
<Button
variant="ghost"
size="icon"
aria-label="Expand all folders"
disabled={openCount === ALL_FOLDERS.length}
onClick={() => setExpanded(ALL_FOLDERS)}
>
<ChevronsUpDown aria-hidden="true" />
</Button>
<Button
variant="ghost"
size="icon"
aria-label="Collapse all folders"
disabled={expanded.length === 0}
onClick={() => setExpanded([])}
>
<ChevronsDownUp aria-hidden="true" />
</Button>
</div>
</div>
<TreeViewFileExplorer
label="Payouts service files"
nodes={EDITABLE_NODES}
value={open}
onValueChange={setOpen}
expanded={expanded}
onExpandedChange={setExpanded}
showPath
/>
<p role="status" className="px-2 text-xs text-muted-foreground">
<span className="font-medium text-foreground tabular-nums">
{openCount} of {ALL_FOLDERS.length}
</span>{" "}
folders open
</p>
</div>
)
}
function TreeViewFileExplorerLoading() {
return (
<div className="grid w-xs max-w-full gap-2">
<p className={MICRO_LABEL}>Ledgerline portal</p>
<TreeViewFileExplorer label="Ledgerline portal files" loading />
</div>
)
}
function TreeViewFileExplorerEmpty() {
return (
<div className="grid w-xs max-w-full gap-2">
<p className={MICRO_LABEL}>Statement exports</p>
<TreeViewFileExplorer
label="Statement export files"
nodes={[]}
emptyLabel="No exports yet. Statements you export from Ledgerline appear here."
emptyAction={
<Button variant="outline">
<Download aria-hidden="true" data-icon="inline-start" />
Export a statement
</Button>
}
/>
</div>
)
}
const MONTHS = [
"january",
"february",
"march",
"april",
"may",
"june",
"july",
"august",
"september",
"october",
"november",
"december",
]
const RECONCILIATION =
"packages/billing/src/reconciliation/providers/adapters"
const MONOREPO_NODES: FileTreeNode[] = [
folder("packages", [
folder("packages/billing", [
folder("packages/billing/src", [
folder("packages/billing/src/reconciliation", [
folder("packages/billing/src/reconciliation/providers", [
folder(RECONCILIATION, [
file(
`${RECONCILIATION}/single-euro-payments-area-direct-debit-settlement-adapter.ts`
),
file(`${RECONCILIATION}/card-network-chargeback-adapter.ts`),
file(`${RECONCILIATION}/index.ts`),
]),
]),
file("packages/billing/src/reconciliation/match-ledger-entries.ts"),
]),
file("packages/billing/src/index.ts"),
]),
file("packages/billing/package.json"),
]),
folder("packages/emails", [
file("packages/emails/invoice-overdue-second-reminder-with-late-fee.mdx"),
file("packages/emails/receipt.mdx"),
]),
]),
folder(
"statements",
MONTHS.map((month) => file(`statements/2026-${month}-settlement-report.json`))
),
folder("public", [
file("public/ledgerline-wordmark-inverted-for-dark-backgrounds.svg"),
file("public/favicon.png"),
]),
file("CONTRIBUTING.md"),
file("LICENSE"),
file("package.json"),
file("pnpm-workspace.yaml"),
file("tsconfig.json"),
]
function TreeViewFileExplorerOverflow() {
return (
<div className="grid w-xs max-w-full gap-2">
<p className={MICRO_LABEL}>Ledgerline monorepo</p>
<TreeViewFileExplorer
label="Ledgerline monorepo files"
nodes={MONOREPO_NODES}
defaultExpanded={[
"packages",
"packages/billing",
"packages/billing/src",
"packages/billing/src/reconciliation",
"packages/billing/src/reconciliation/providers",
RECONCILIATION,
"packages/emails",
"statements",
"public",
]}
defaultValue={`${RECONCILIATION}/single-euro-payments-area-direct-debit-settlement-adapter.ts`}
showPath
/>
</div>
)
}
export const scenarios = {
"collapsed-selection": TreeViewFileExplorerCollapsedSelection,
controlled: TreeViewFileExplorerControlled,
disabled: TreeViewFileExplorerDisabled,
loading: TreeViewFileExplorerLoading,
empty: TreeViewFileExplorerEmpty,
overflow: TreeViewFileExplorerOverflow,
}
Props15
- nodes
- FileTreeNode[] = DEFAULT_NODES
- value
- string | null
- Id of the open file. Pass `null` for none.
- defaultValue
- string | null = null
- onValueChange
- (value: string | null) => void
- expanded
- string[]
- defaultExpanded
- string[] = DEFAULT_EXPANDED
- onExpandedChange
- (expanded: string[]) => void
- label
- string = "Files"
- Accessible name of the tree.
- loading
- boolean = false
- Shows skeleton rows and marks the tree busy.
- showPath
- boolean = false
- Adds a line under the tree with the path of the open file and the file count.
- emptyLabel
- string = "No files yet. Files added to this project appear here."
- emptyAction
- React.ReactNode
- One action offered under the empty message.
- noSelectionLabel
- string = "No file open"
- Path line text while no file is open.
- containsSelectionLabel
- string = "Contains the open file"
- Read out on a closed folder that holds the open file.
- formatCount
- (count: number) => string = defaultFormatCount
Also accepts every prop of Omit< React.ComponentProps<"div">, "children" | "defaultValue" | "onChange" >.
Accessibility
- Keyboard
Keyboard support for File Tree Key Effect Tab Enters the tree on the last focused row, the open file or the first row, and leaves it again Arrow Down, Arrow Up Moves focus to the next or previous visible row Arrow Right Opens a closed folder, or moves into the first child of an open one. Arrow Left does this in right to left layouts Arrow Left Closes an open folder, or moves to the parent folder. Arrow Right does this in right to left layouts. A disabled folder stays as it is Home, End Moves focus to the first or last visible row Enter or Space Opens the focused file, or opens and closes the focused folder. Does nothing on a disabled row Asterisk Opens every folder at the same level as the focused row, except disabled ones Letters and digits Moves focus to the next visible row whose name starts with the typed characters. Repeating one character steps through its matches - Screen reader
A labelled tree of treeitem rows with aria-level, aria-setsize and aria-posinset, aria-expanded on folders and aria-selected on files. Rows are divs with the treeitem role because no native element carries it, and each group is a sibling of its row so the name and focus outline cover one row. Disabled rows carry aria-disabled and stay reachable with the arrow keys.
- Reduced motion
- The chevron turns without a transition and skeleton rows do not pulse. Colour transitions only.
- Checked
- Not checked yet. Automated results appear here once CI has run.
Dependencies2
- @hazine/use-controllable-state
- lucide-react
Filled chips are registry items the CLI adds for you. Outlined chips are npm packages.
Tokens shipped0
None. The item is styled by the tokens your theme already has.