File manager

A React block (a whole screen) in Beamline's Blocks category.

Files and folders in one screen: the views (My files, Shared, Recent, Starred, Trash) with storage at the foot, a folder tree beside the files, breadcrumb, search across folders, grid or list, Upload as the one primary action, and a file's preview, details, people and Share in a side panel; rename, trash, restore, star and share are optimistic.

Use it for

A product's files area: a team drive, a client portal's documents, an asset library — browse folders, upload, preview, share.

Not for

Picking files for one form field (file-dropzone).
A single image gallery without folders (lightbox).

Anatomy

app shell: the views as navigation (Trash with its count), storage meter at the foot, Upload in the top bar
folder tree beside the files from 55rem of room
toolbar: breadcrumb of the folder path, search across every folder, New folder, Grid / List
files: tiles (image thumbnails open full screen; other kinds a typed glyph) or a list (name, owner, modified, size; owner and dates fold into the name line in a narrow room); every item has a right-click / long-press / Shift+F10 menu
details panel: preview, the name (rename in place), Share, Move to trash, kind, size, where, owner, modified, who has access
upload dialog (drop or choose, progress per file), new folder dialog, share dialog (invite by email with access, people with access, Copy link)

States

loading (tiles hold their shape)
failed to load (the error with Try again)
an empty folder (Upload offered), an empty view, Trash empty
no file matches the search (Clear search)
an upload in progress, done, failed with retry (the drop zone's own)
a change refused (the item goes back; the reason sits under the toolbar with Try again)
storage near the limit (the meter warns)
size not known (hatched)

Keyboard

Tab reaches each tile's open button; Shift+F10 or the menu key opens its menu
the folder tree has the full tree keyboard (arrows, Home/End, type to jump)
Enter renames in place; Esc cancels
the image viewer: ← → between images, Esc closes and returns to the thumbnail

Motion

An image thumbnail grows into the full-screen viewer and back (the lightbox's own); list rows slide when the folder's contents change (TableBody flip); the details panel slides in on --motion-in; Grid / List's thumb travels. Reduced motion: changes are immediate.

Props

Prop	Type	Default	Description
`items / defaultItems / onItemsChange`	`FileItem[]`	—	Every file and folder, flat, with parent ids.
`folder / defaultFolder / onFolderChange`	`string \| null`	—
`onUpload`	`(file, folder, { onProgress, signal }) => Promise<FileItem \| void>`	—	Shows Upload.
`onChange`	`(id, patch: { name?, trashed?, starred?, parent? }) => Promise<void> \| void`	—
`onCreateFolder`	`(name, parent) => Promise<FileItem \| void> \| void`	—	Shows New folder.
`onShare`	`(id, person: SharePerson) => Promise<void> \| void`	—	Shows Share.
`linkFor`	`(item: FileItem) => string`	—
`storage`	`{ used: { label: string; value: number }[]; limit: number }`	—	Bytes, by kind.
`me`	`string`	—
`loading / error / onRetry`	`boolean / Error \| null / () => void`	—
`product`	`string`	`"Northline Files"`
`className / style / ref`	`string / CSSProperties / Ref<HTMLDivElement>`	—

Built from

app-shell
usage-meter
tree-view
breadcrumb
search-field
segmented-control
context-menu
lightbox
table
sheet
inline-edit
dialog
file-dropzone
input
select
copy-button
avatar
button
alert
empty-state
skeleton

Dependencies

lucide-react

Import

import { FileManager } from "@/blocks/file-manager/file-manager";

Get it

File manager is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. Get Beamline · Connect your agent