# File System

> 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.

- Type: React component (Media)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add file-system`
- Docs: https://wingo-ui.com/components/file-system

## Interaction

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.

## Installation

```bash
npx wingo-ui@latest add file-system
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/file-system` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/file-system.tsx`

npm dependencies: `npm i @tanstack/react-virtual lucide-react`

Wingo UI dependencies (installed automatically):

- [Alert Dialog](https://wingo-ui.com/components/alert-dialog) ([Markdown](https://wingo-ui.com/components/alert-dialog.md))
- [Audio Player](https://wingo-ui.com/components/audio-player) ([Markdown](https://wingo-ui.com/components/audio-player.md))
- [Breadcrumb](https://wingo-ui.com/components/breadcrumb) ([Markdown](https://wingo-ui.com/components/breadcrumb.md))
- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Code Block](https://wingo-ui.com/components/code-block) ([Markdown](https://wingo-ui.com/components/code-block.md))
- [Command Menu](https://wingo-ui.com/components/command-menu) ([Markdown](https://wingo-ui.com/components/command-menu.md))
- [Context Menu](https://wingo-ui.com/components/context-menu) ([Markdown](https://wingo-ui.com/components/context-menu.md))
- [CSV Viewer](https://wingo-ui.com/components/csv-viewer) ([Markdown](https://wingo-ui.com/components/csv-viewer.md))
- [Dialog](https://wingo-ui.com/components/dialog) ([Markdown](https://wingo-ui.com/components/dialog.md))
- [DOCX Viewer](https://wingo-ui.com/components/docx-viewer) ([Markdown](https://wingo-ui.com/components/docx-viewer.md))
- [Dropdown Menu](https://wingo-ui.com/components/dropdown-menu) ([Markdown](https://wingo-ui.com/components/dropdown-menu.md))
- [Excel Viewer](https://wingo-ui.com/components/excel-viewer) ([Markdown](https://wingo-ui.com/components/excel-viewer.md))
- [File types](https://wingo-ui.com/components/file-types) ([Markdown](https://wingo-ui.com/components/file-types.md))
- [File Upload](https://wingo-ui.com/components/file-upload) ([Markdown](https://wingo-ui.com/components/file-upload.md))
- [Image Lightbox](https://wingo-ui.com/components/image-lightbox) ([Markdown](https://wingo-ui.com/components/image-lightbox.md))
- [Markdown](https://wingo-ui.com/components/markdown) ([Markdown](https://wingo-ui.com/components/markdown.md))
- [PDF Viewer](https://wingo-ui.com/components/pdf-viewer) ([Markdown](https://wingo-ui.com/components/pdf-viewer.md))
- [Popover](https://wingo-ui.com/components/popover) ([Markdown](https://wingo-ui.com/components/popover.md))
- [PowerPoint Viewer](https://wingo-ui.com/components/pptx-viewer) ([Markdown](https://wingo-ui.com/components/pptx-viewer.md))
- [Relative time](https://wingo-ui.com/components/relative-time) ([Markdown](https://wingo-ui.com/components/relative-time.md))
- [Sheet](https://wingo-ui.com/components/sheet) ([Markdown](https://wingo-ui.com/components/sheet.md))
- [Text match](https://wingo-ui.com/components/text-match) ([Markdown](https://wingo-ui.com/components/text-match.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [Tree View](https://wingo-ui.com/components/tree-view) ([Markdown](https://wingo-ui.com/components/tree-view.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))
- [useClipboard](https://wingo-ui.com/components/use-clipboard) ([Markdown](https://wingo-ui.com/components/use-clipboard.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [useLocale](https://wingo-ui.com/components/use-locale) ([Markdown](https://wingo-ui.com/components/use-locale.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))
- [useShortcut](https://wingo-ui.com/components/use-shortcut) ([Markdown](https://wingo-ui.com/components/use-shortcut.md))
- [Video Player](https://wingo-ui.com/components/video-player) ([Markdown](https://wingo-ui.com/components/video-player.md))

## Usage

```tsx
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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items?` | `FileSystemNode[]` |  | 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. |
| `rootLabel?` | `string` | `""` | The name of the root in the sidebar, the title and the path bar. Empty uses labels.root (Home). |
| `tags?` | `FileSystemTag[]` |  | Colored tags ({ id, label, color }) listed in the sidebar; a tag opens everything that has it. Nodes reference them by id. |
| `locations?` | `FileSystemLocation[]` |  | Rows under Locations: { id, label, folderId, icon? }. The root by default. |
| `defaultView?` | `"icons" \| "list" \| "columns" \| "gallery"` | `"icons"` | The view it opens in. ⌘1 to ⌘4 and the toolbar switch it; view and onViewChange control it. |
| `iconSize?` | `"sm" \| "md" \| "lg"` | `"md"` | Tiles of the Icons view: 88, 104 or 128px wide. |
| `foldersFirst?` | `boolean` | `true` | Folders before files in every sort, like Finder's Keep folders on top. |
| `searchScope?` | `"all" \| "folder"` | `"all"` | Where search looks: the whole tree, or the open folder and everything below it. |
| `confirmDelete?` | `boolean` | `true` | Asks before deleting (an alert dialog that waits for onDelete's promise); the action reads Delete… while it does. |
| `accept?` | `string` | `""` | File types the upload takes (".pdf,image/*"). Other files are listed as not uploaded. |
| `maxFileSize?` | `number` | `0` | Bytes per uploaded file; bigger files are listed as not uploaded. 0 means no limit. |
| `commandShortcut?` | `string` | `""` | Opens the Go to palette (actions, places and every file) from anywhere, in mod+k notation. Empty binds nothing; the palette stays in the ⋯ menu. |
| `locale?` | `string` | `"en-US"` | Locale for sizes, dates, relative times and the sort order of names. Unset, it follows the UIProvider locale, then the browser's. |
| `loading?` | `boolean` | `false` | Skeleton tiles or rows in place of the open folder, for a tree that is still on its way. |
| `error?` | `ReactNode` | `""` | Replaces the files with an error state and this text; onRetry adds Try again. |
| `showToolbar?` | `boolean` | `true` | The toolbar: sidebar, back and forward, the folder name, views, sort, new folder, upload, preview, search and the ⋯ menu. |
| `showSidebar?` | `boolean` | `true` | Favorites, locations and tags; a sheet below 560px of width. |
| `defaultSidebarOpen?` | `boolean` | `true` | Whether the sidebar starts open where there is room for it. |
| `sidebarWidth?` | `number` | `200` | Starting width of the sidebar in px (160 to 320); drag its edge or use the arrow keys on it, double-click resets it. |
| `showRecents?` | `boolean` | `true` | A Recents location: the 100 most recently modified files. |
| `defaultPreviewOpen?` | `boolean` | `true` | The preview panel beside the files (from 900px of width): the selection's thumbnail, details, tags, download and delete. ⇧⌘P toggles it. |
| `showPathBar?` | `boolean` | `true` | The path bar under the files; every crumb opens that folder and takes dropped items. |
| `showStatusBar?` | `boolean` | `true` | Item and selection counts, and what is running (Moving, Uploading). |
| `showSearch?` | `boolean` | `true` | The search field (a button and a sheet when narrow) and ⌘F / Ctrl+F inside the component. |
| `height?` | `number \| string` | `640` | Height of the frame: px as a number, or any CSS length ("100%", "80dvh") to fill a pane. |
| `variant?` | `"surface" \| "outline" \| "plain"` | `"surface"` | surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own. |
| `radius?` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Corner radius of the frame: 0, 12, 16 or 24px. |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Selected rows and name tags, the open sidebar row and drop targets. Neutral is black in light mode and white in dark mode. |
| `color?` | `string` | `""` | Any CSS color; replaces the tone (text on it turns black or white by its lightness). |
| `folderColor?` | `string` | `"#4f9ef5"` | The folder glyphs, back plate in this color and front plate lighter. Also --file-system-folder on the frame. |
| `folderId?` | `string \| null` |  | The open folder, controlled (null is the root). Pair it with onFolderChange. |
| `defaultFolderId?` | `string \| null` | `""` | The folder it opens in, uncontrolled; null or empty is the root. The playground offers folders of the sample drive. |
| `onFolderChange?` | `(folderId: string \| null) => void` |  | Called when another folder opens (double-click, the path bar, the sidebar, back and forward). |
| `selectedIds?` | `string[]` |  | The selection, controlled. Pair it with onSelectionChange. |
| `defaultSelectedIds?` | `string[]` | `"[]"` | The selection it starts with, uncontrolled. |
| `onSelectionChange?` | `(ids: string[], nodes: FileSystemNode[]) => void` |  | Called 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) => void` |  | Called when the toolbar, the ⋯ menu, the palette or ⌘1 to ⌘4 switch the view. |
| `sort?` | `FileSystemSort` |  | The order, controlled: { key: "name" \| "kind" \| "size" \| "modified" \| "created", direction: "asc" \| "desc" }. |
| `defaultSort?` | `FileSystemSort` | `"{ key: \"name\", direction: \"asc\" }"` | The order it starts with, uncontrolled. |
| `onSortChange?` | `(sort: FileSystemSort) => void` |  | Called when a list header or the sort menu changes the order. |
| `favorites?` | `string[]` |  | Ids under Favorites in the sidebar, controlled. Add to favorites / Remove from favorites change it. |
| `defaultFavorites?` | `string[]` | `"[]"` | The favorites it starts with, uncontrolled. |
| `onFavoritesChange?` | `(ids: string[]) => void` |  | Called with the new list of favorite ids. |
| `onOpen?` | `(file: FileSystemNode, event: FileSystemOpenEvent) => void` |  | Called when a file is opened (double-click, Enter, a tap). event.preventDefault() keeps the lightbox or Quick Look from opening. |
| `onPreviewChange?` | `(file: FileSystemNode \| null) => void` |  | Called 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[]) => void` |  | Replaces 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) => void` |  | Called 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. |
| `toolbarActions?` | `ReactNode` |  | Your own buttons at the end of the toolbar, before the ⋯ menu: share, request files, sync. |
| `now?` | `Date \| number` |  | Relative times (5 minutes ago) are measured from it. Unset, the clock is read after hydration; demos pin it. |
| `ref?` | `Ref<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(). |
| `labels?` | `Partial<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. |
| `classNames?` | `Partial<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. |
| `className?` | `string` |  | Extra classes for the frame, merged last. Other div props are forwarded to it. |

## Parts

### FileSystemNode (type)

A 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 (type)

A sidebar tag: { id, label, color }.

### FileSystemLocation (type)

A row under Locations: { id, label, folderId (null is the root), icon? }.

### FileSystemHandle (type)

What 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 (type)

What onOpen receives as its second argument: preventDefault() and defaultPrevented.

### FileSystemLabels (type)

The shape of labels: every string the component renders.

### DEFAULT_FILE_SYSTEM_LABELS (constant)

The English labels. Spread it to translate a few strings.

### DEFAULT_FILE_SYSTEM_SORT (constant)

The 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.

## See also

- [File manager](https://wingo-ui.com/components/file-manager) ([Markdown](https://wingo-ui.com/components/file-manager.md))
- [PDF Viewer](https://wingo-ui.com/components/pdf-viewer) ([Markdown](https://wingo-ui.com/components/pdf-viewer.md))
- [Excel Viewer](https://wingo-ui.com/components/excel-viewer) ([Markdown](https://wingo-ui.com/components/excel-viewer.md))
- [Tree View](https://wingo-ui.com/components/tree-view) ([Markdown](https://wingo-ui.com/components/tree-view.md))
- [File List](https://wingo-ui.com/components/file-list) ([Markdown](https://wingo-ui.com/components/file-list.md))

---

Canonical: https://wingo-ui.com/components/file-system
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt
