File System React component for Tailwind CSS v4
v1.0.0Added in 1.4.0
A React file browser in the style of Finder: a sidebar, icons, list, columns and gallery views, a preview panel and Quick Look on real documents.
Browse folders like in Finder. The sidebar lists favorites, locations (Recents and your roots) and colored tags; drag its edge to resize it, the panel button or Alt+⌘S hides it, and in a narrow frame it opens as a sheet. Four views: Icons (a grid of thumbnails), List (Name, Date modified, Size and Kind columns, click a header to sort, the chevron opens a folder in place), Columns (a column per folder level and a preview of the selected file; on phones one level at a time with a back row) and Gallery (a large live preview with a filmstrip). Every view is virtualized, so a folder of 10,000 files scrolls and sorts instantly. Click to select, Shift+click for a range, ⌘ / Ctrl+click to add, drag across empty space for a rectangle, ⌘A for all; arrows move, Shift+arrows extend, typing a name jumps to it. Double-click or Enter opens: folders open in place, images in the lightbox, other files in Quick Look; Space opens Quick Look on any file (PDF, Word, Excel, CSV, PowerPoint, images, video, audio, Markdown, JSON, code and text) and the arrows move through the folder. Back and forward (⌘[ ⌘]), Backspace or ⌘↑ go up, the path bar at the bottom jumps to any parent. Right-click, Shift+F10, a long press or the ⋯ of a row opens the actions: open, Get info (⌘I), rename (F2, Enter saves, Escape cancels), duplicate (⌘D), move to, copy to, copy and paste (⌘C, ⌘V, ⌥⌘V moves), download, copy path, favorites, tags and delete (⌘⌫, with a confirmation). Drag items onto a folder, a crumb or a sidebar row to move them (hold ⌥ to copy, rest on a folder to spring it open), onto a tag to tag them; drop files from the desktop to upload them. Search (⌘F) looks through the whole tree, accents and case ignored, with a 2 of 14 counter and Enter / Shift+Enter between results. The preview panel shows the selection's details. Menus, the search and dialogs become bottom sheets on phones, where rows are 44px or taller and a tap opens.
File System is a Pro React component in the React media components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add file-system, together with Alert Dialog, Audio Player, Breadcrumb, Button, Code Block and 27 more and the npm packages @tanstack/react-virtual and lucide-react.
Add to a project
Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup
npx wingo-ui@latest add file-systemFile System is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans
Usage
Import FileSystem from @/components/ui/file-system.
import { FileSystem, type FileSystemNode } from "@/components/ui/file-system"
const items: FileSystemNode[] = [
{
id: "documents",
name: "Documents",
kind: "folder",
children: [
{ id: "report", name: "Q3 sales report.xlsx", kind: "file", size: 145926, url: "/files/q3-sales-report.xlsx" },
{ id: "agreement", name: "Service agreement.pdf", kind: "file", size: 7905, url: "/files/service-agreement.pdf" },
],
},
{ id: "readme", name: "README.md", kind: "file", url: "/files/readme.md" },
]
export function Drive() {
return (
<FileSystem
items={items}
height="80dvh"
onSelectionChange={(ids) => console.log(ids)}
onRename={async (node, name) => {
await fetch(`/api/files/${node.id}`, { method: "PATCH", body: JSON.stringify({ name }) })
}}
/>
)
}Props
itemsFileSystemNode[]The tree, nested (children) or flat (parentId), or both. A node is { id, name, kind: "file" | "folder", size?, modified?, created?, mime?, url?, thumbnail?, tags?, locked?, info?, hasChildren? }. Files with a url open in the viewers; the rest show their details.
loadChildren(folder: FileSystemNode | null) => Promise<FileSystemNode[]>Fetches the contents of a folder with hasChildren the first time it is shown (null: the root, when items is empty). Skeleton rows while it runs, a Try again state when it rejects.
resolveUrl((file: FileSystemNode) => string | Promise<string>)A url for files that have none yet (a presigned link), asked once per file when it is previewed or downloaded.
rootLabeldefault""stringThe name of the root in the sidebar, the title and the path bar. Empty uses labels.root (Home).
tagsFileSystemTag[]Colored tags ({ id, label, color }) listed in the sidebar; a tag opens everything that has it. Nodes reference them by id.
locationsFileSystemLocation[]Rows under Locations: { id, label, folderId, icon? }. The root by default.
defaultViewdefault"icons""icons" | "list" | "columns" | "gallery"The view it opens in. ⌘1 to ⌘4 and the toolbar switch it; view and onViewChange control it.
iconSizedefault"md""sm" | "md" | "lg"Tiles of the Icons view: 88, 104 or 128px wide.
foldersFirstdefaulttruebooleanFolders before files in every sort, like Finder's Keep folders on top.
searchScopedefault"all""all" | "folder"Where search looks: the whole tree, or the open folder and everything below it.
confirmDeletedefaulttruebooleanAsks before deleting (an alert dialog that waits for onDelete's promise); the action reads Delete… while it does.
acceptdefault""stringFile types the upload takes (".pdf,image/*"). Other files are listed as not uploaded.
maxFileSizedefault0numberBytes per uploaded file; bigger files are listed as not uploaded. 0 means no limit.
commandShortcutdefault""stringOpens the Go to palette (actions, places and every file) from anywhere, in mod+k notation. Empty binds nothing; the palette stays in the ⋯ menu.
localedefault"en-US"stringLocale for sizes, dates, relative times and the sort order of names. Unset, it follows the UIProvider locale, then the browser's.
loadingdefaultfalsebooleanSkeleton tiles or rows in place of the open folder, for a tree that is still on its way.
errordefault""ReactNodeReplaces the files with an error state and this text; onRetry adds Try again.
showToolbardefaulttruebooleanThe toolbar: sidebar, back and forward, the folder name, views, sort, new folder, upload, preview, search and the ⋯ menu.
showSidebardefaulttruebooleanFavorites, locations and tags; a sheet below 560px of width.
defaultSidebarOpendefaulttruebooleanWhether the sidebar starts open where there is room for it.
sidebarWidthdefault200numberStarting width of the sidebar in px (160 to 320); drag its edge or use the arrow keys on it, double-click resets it.
showRecentsdefaulttruebooleanA Recents location: the 100 most recently modified files.
defaultPreviewOpendefaulttruebooleanThe preview panel beside the files (from 900px of width): the selection's thumbnail, details, tags, download and delete. ⇧⌘P toggles it.
showPathBardefaulttruebooleanThe path bar under the files; every crumb opens that folder and takes dropped items.
showStatusBardefaulttruebooleanItem and selection counts, and what is running (Moving, Uploading).
showSearchdefaulttruebooleanThe search field (a button and a sheet when narrow) and ⌘F / Ctrl+F inside the component.
heightdefault640number | stringHeight of the frame: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
variantdefault"surface""surface" | "outline" | "plain"surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
radiusdefault"md""none" | "sm" | "md" | "lg"Corner radius of the frame: 0, 12, 16 or 24px.
tonedefault"neutral""neutral" | "brand" | "success" | "warning" | "danger" | "info"Selected rows and name tags, the open sidebar row and drop targets. Neutral is black in light mode and white in dark mode.
colordefault""stringAny CSS color; replaces the tone (text on it turns black or white by its lightness).
folderColordefault"#4f9ef5"stringThe folder glyphs, back plate in this color and front plate lighter. Also --file-system-folder on the frame.
folderIdstring | nullThe open folder, controlled (null is the root). Pair it with onFolderChange.
defaultFolderIddefault""string | nullThe folder it opens in, uncontrolled; null or empty is the root. The playground offers folders of the sample drive.
onFolderChange(folderId: string | null) => voidCalled when another folder opens (double-click, the path bar, the sidebar, back and forward).
selectedIdsstring[]The selection, controlled. Pair it with onSelectionChange.
defaultSelectedIdsdefault"[]"string[]The selection it starts with, uncontrolled.
onSelectionChange(ids: string[], nodes: FileSystemNode[]) => voidCalled with the ids and the nodes whenever the selection changes.
view"icons" | "list" | "columns" | "gallery"The view, controlled. Pair it with onViewChange.
onViewChange(view: FileSystemView) => voidCalled when the toolbar, the ⋯ menu, the palette or ⌘1 to ⌘4 switch the view.
sortFileSystemSortThe order, controlled: { key: "name" | "kind" | "size" | "modified" | "created", direction: "asc" | "desc" }.
defaultSortdefault"{ key: "name", direction: "asc" }"FileSystemSortThe order it starts with, uncontrolled.
onSortChange(sort: FileSystemSort) => voidCalled when a list header or the sort menu changes the order.
favoritesstring[]Ids under Favorites in the sidebar, controlled. Add to favorites / Remove from favorites change it.
defaultFavoritesdefault"[]"string[]The favorites it starts with, uncontrolled.
onFavoritesChange(ids: string[]) => voidCalled with the new list of favorite ids.
onOpen(file: FileSystemNode, event: FileSystemOpenEvent) => voidCalled when a file is opened (double-click, Enter, a tap). event.preventDefault() keeps the lightbox or Quick Look from opening.
onPreviewChange(file: FileSystemNode | null) => voidCalled when Quick Look opens a file, moves to another one, or closes (null).
onCreateFolder((parentId: string | null, name: string) => void | Promise<unknown>)Enables New folder (⇧⌘N): a folder appears with its name selected; Enter calls this. A rejected promise keeps the name and shows why.
onRename((node: FileSystemNode, name: string) => void | Promise<unknown>)Enables rename: F2, the menu, or a slow second click on the name. Enter saves, Escape cancels; a rejected promise keeps the text and shows its message.
onMove((nodes: FileSystemNode[], targetId: string | null) => void | Promise<unknown>)Enables moving: drag onto a folder, a crumb or a sidebar row, Move to…, or ⌥⌘V after ⌘C. A folder never goes into itself.
onCopy((nodes: FileSystemNode[], targetId: string | null) => void | Promise<unknown>)Enables copying: ⌥ while dragging, Copy to…, Duplicate (⌘D, into the same folder) and ⌘C then ⌘V.
onDelete((nodes: FileSystemNode[]) => void | Promise<unknown>)Enables Delete (⌘⌫ or Delete), after a confirmation unless confirmDelete is off. Locked nodes are never passed.
onUpload((files: File[], targetId: string | null) => void | Promise<unknown>)Enables Upload files and dropping files from the desktop onto the view, a folder, a crumb or a sidebar row. accept and maxFileSize filter first.
onDownload(nodes: FileSystemNode[]) => voidReplaces the built-in download (a link per file with a url or a resolved url).
onTagChange((nodes: FileSystemNode[], tagId: string, add: boolean) => void | Promise<unknown>)Enables tagging: the Tags submenu, the tag buttons in Get info, and dropping items onto a sidebar tag.
onLoadError(error: unknown, folder: FileSystemNode | null) => voidCalled when loadChildren rejects; the folder shows the error with Try again.
onRetry(() => void | Promise<unknown>)Adds Try again to the error state; a returned promise shows it loading.
toolbarActionsReactNodeYour own buttons at the end of the toolbar, before the ⋯ menu: share, request files, sync.
nowDate | numberRelative times (5 minutes ago) are measured from it. Unset, the clock is read after hydration; demos pin it.
refRef<FileSystemHandle> (a useRef object or an (handle) => void callback)open(id or path), goBack(), goForward(), goUp(), select(ids), getSelection(), getCurrentFolder(), refresh(), openPreview(id?), closePreview() and getViewportElement().
labelsPartial<FileSystemLabels>Every string, English by default (DEFAULT_FILE_SYSTEM_LABELS): toolbar, sidebar, menus, states, dialogs and announcements, including items(count, formatted), results(active, total), deleteTitle(count, name), busy and kinds.
classNamesPartial<Record<"toolbar" | "sidebar" | "sidebarItem" | "content" | "item" | "name" | "preview" | "pathBar" | "statusBar" | "quickLook" | "state", string>>Extra classes for the toolbar, the sidebar and its rows, the content, every tile or row and its name, the preview panel, the path bar, the status bar, Quick Look and the empty, loading and error states.
classNamestringExtra classes for the frame, merged last. Other div props are forwarded to it.
Parts
FileSystemNode
typeA file or folder: id, name, kind, parentId or children, hasChildren (lazy), size, modified, created, mime, url, thumbnail, tags (tag ids), locked and info (extra rows for the details, like Owner).
FileSystemTag
typeA sidebar tag: { id, label, color }.
FileSystemLocation
typeA row under Locations: { id, label, folderId (null is the root), icon? }.
FileSystemHandle
typeWhat the ref gets: open(target) with an id or a path of names ("Documents/Q3 2026/Sales"), which returns false when nothing matches; goBack(), goForward(), goUp(), select(ids), getSelection(), getCurrentFolder(), refresh(), openPreview(id?), closePreview() and getViewportElement().
FileSystemSort
type{ key: "name" | "kind" | "size" | "modified" | "created", direction: "asc" | "desc" }.
FileSystemOpenEvent
typeWhat onOpen receives as its second argument: preventDefault() and defaultPrevented.
FileSystemLabels
typeThe shape of labels: every string the component renders.
DEFAULT_FILE_SYSTEM_LABELS
constantThe English labels. Spread it to translate a few strings.
DEFAULT_FILE_SYSTEM_SORT
constantThe default order: { key: "name", direction: "asc" }.
Examples
Selection outside the component
onSelectionChange hands over the selected nodes, onOpen the file someone double-clicked; Shift and ⌘ / Ctrl pick several.
Every view, controlled
view and onViewChange drive Icons, List, Columns and Gallery from outside; ⌘1 to ⌘4 switch them from the keyboard.
Operations that return promises
Rename, new folder, move (drag onto a folder, ⌥ copies), copy, delete and upload wait for the promise; a rejected save keeps the name you typed.
Your own toolbar actions and a command palette
toolbarActions adds Share and Request files; commandShortcut="mod+k" opens Go to, which finds any file in the tree.
On a phone
Locations open as a sheet, rows are two lines and 56px tall, a tap opens, a long press or ⋯ shows the actions, columns go one level at a time.
Lazy folders, errors and an empty folder
loadChildren fetches a folder the first time it opens (skeleton rows meanwhile); Archive fails once and offers Try again.
Romanian locale
locale="ro-RO" formats dates (23 sept. 2026), relative times (acum 3 ore) and sizes; labels stay in English unless you pass labels.
50,000 files
A folder with 10,000 files and a ten-year archive: sorting, search and every view stay instant because only the visible rows render.
Dependencies
Files
- components/ui/file-system.tsx
FAQ
Is the React File System component free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install File System?
Run npx wingo-ui@latest add file-system. It also adds the Wingo UI items it builds on (Alert Dialog, Audio Player, Breadcrumb, Button, Code Block and 27 more) and the npm packages @tanstack/react-virtual and lucide-react. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/file-system.
How does File System behave on phones?
Four views: Icons (a grid of thumbnails), List (Name, Date modified, Size and Kind columns, click a header to sort, the chevron opens a folder in place), Columns (a column per folder level and a preview of the selected file; on phones one level at a time with a back row) and Gallery (a large live preview with a filmstrip).
See also
More React media components
Articles using this component
- React File Manager: Folders, Uploads and the Backend API
Component guides10 min read
New components by email
New posts, product news and occasional offers from Wingo UI. We count clicks to keep it relevant.