File browser

Explores a supplied file hierarchy through folders, breadcrumbs, search, and list or grid views.

Preview

In action

The working files

When to use

Use it for

Browsing a supplied file tree and choosing a file.
Folder-local search with consistent selection in list and grid views.

Not for

Direct filesystem access or cloud storage sync; the application supplies data and actions.

Install

Three ways in. They share one source, so the pixels match whichever you pick.

1. Import the package

npm install @noorddev/vlak-react

// once, next to your app's root
import "@noorddev/vlak-react/css";

import { FileBrowser } from "@noorddev/vlak-react";

Precompiled React and one stylesheet. No compiler to configure. Per-component imports work too: @noorddev/vlak-react/components/file-browser.

2. Vendor the source

npx @noorddev/vlak-cli add file-browser

The StyleX leaf lands in components/vlak/ with its dependencies, for your own compiler to own. See StyleX.

3. Through shadcn

npx shadcn add https://vlak.dev/r/file-browser.json

The same registry item, installed by shadcn's CLI.

CSS only

<link rel="stylesheet" href="node_modules/@noorddev/vlak/css/vlak.css" />

No React. Link vlak.css and use the markup and classes below.

React

import { FileBrowser } from "@noorddev/vlak-react";

<FileBrowser entries={[{ id: "design", name: "Design", kind: "folder", children: [{ id: "cover", name: "Cover.pdf", kind: "file", size: "1.2 MB" }] }]} onOpen={openFile} />

Props

FileBrowser

A controlled file collection with folder tree, breadcrumbs, search, and list or grid views.

Prop	Type	Default	Description
`entries`required	`BrowserEntry[]`
`label`	`string`	`"Files"`
`rootLabel`	`string`	`"Files"`	Visible root-folder name, separate from the accessible browser label.
`value`	`string`
`defaultValue`	`string`
`onValueChange`	`(id: string) => void`
`folder`	`string \| null`
`defaultFolder`	`string \| null`	`null`
`onFolderChange`	`(id: string \| null) => void`
`onOpen`	`(entry: BrowserEntry) => void`

Also accepts Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" | "onSelect">.

Keyboard

Keys	Does
`Arrow keys, Home, End, type-ahead`	Navigates the folder tree using its roving focus behavior.
`Tab, Enter, Space`	Uses breadcrumbs, selects files, switches view, and activates Open selected.

Accessibility

Folder tree, breadcrumbs, search, and file collection each have names.
label names the region and its landmarks; rootLabel supplies the visible root folder name.
Selected files use aria-pressed and a full surface change.
Files can be opened by an explicit keyboard-operable action as well as double click.

Markup

<div class="rs-file-browser" role="region" aria-label="Files"><nav aria-label="Folder breadcrumbs">Files</nav><ul class="rs-file-browser-list"><li><button class="rs-file-browser-item" type="button" aria-pressed="false">Cover.pdf</button></li></ul></div>

Classes

.rs-file-browser.rs-file-browser-toolbar.rs-file-browser-breadcrumbs.rs-file-browser-path.rs-file-browser-crumb-item.rs-file-browser-crumb.rs-file-browser-crumb-current.rs-file-browser-action.rs-file-browser-body.rs-file-browser-tree.rs-file-browser-content.rs-file-browser-list.rs-file-browser-grid.rs-file-browser-name.rs-file-browser-meta.rs-file-browser-empty.rs-file-browser-view-active.rs-file-browser-item.rs-file-browser-tile.rs-file-browser-selected

Depends on

/icons /input /tree-view