Skip to content

armgit / ui

Public Imported from GitHub
0
TypeScript
11.4 KB
Raw Blame
---
title: File System (Finder)
description: A macOS Finder-style file browser for flat object-store manifests with icon, list, column, and gallery views.
component: true
---

File System renders a flat manifest of files and folders — the shape you get back from S3, R2, or any key-prefix object store — as a macOS Finder-style browser. It derives the folder hierarchy from object keys, switches between icon, list, column, and gallery views, and treats thumbnails, URLs, and signing as external concerns.

<FileSystemDemo />

## Installation

<CodeTabs>

<TabsList>
  <TabsTrigger value="cli">Command</TabsTrigger>
  <TabsTrigger value="manual">Manual</TabsTrigger>
</TabsList>
<TabsContent value="cli">

```bash
npx shadcn@latest add @extend/file-system
```

</TabsContent>

<TabsContent value="manual">

<Steps className="mb-0 pt-2">

<Step>
  Install the dependencies and the `file-thumbnail` and `tabs` registry items.
</Step>

```bash
npm install @pierre/trees
```

<Step>Install the icon library configured in your `components.json`:</Step>

The component source references icons through the shadcn CLI's
`IconPlaceholder`, which supports every `iconLibrary` the CLI does: `lucide`,
`tabler`, `hugeicons`, `phosphor`, and `remixicon`. Installing with the CLI
replaces each placeholder with the matching icon from your configured library,
so make sure that library's package is installed. When copying the source
manually, replace each `IconPlaceholder` element with the icon named by the
prop for your library.

<Step>
  Copy `components/extend/file-system.tsx` from the registry item into your
  project.
</Step>

<FileSystemSource />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsContent>

</CodeTabs>

## Data Model

The component accepts a normalized flat manifest instead of a nested tree. Files are addressable objects, folders are prefixes, URLs are optional, and signing happens outside the component.

```ts
const items: FileSystemItem[] = [
  {
    kind: "folder",
    path: "invoices/2026/",
    hasChildren: true,
  },
  {
    kind: "file",
    key: "invoices/2026/jan.pdf",
    path: "invoices/2026/jan.pdf",
    contentType: "application/pdf",
    size: 482193,
    createdAt: "2026-01-04T10:02:00.000Z",
    updatedAt: "2026-06-09T18:21:00.000Z",
    etag: '"abc123"',
    previewImageUrl: "/thumbnails/invoices/2026/jan.png",
  },
]
```

Explicit folder entries are optional — missing prefixes are inferred from file paths. Keeping `kind: "folder"` support matters for paginated or lazy traversal, where S3 `CommonPrefixes` describe folders whose contents have not been listed yet.

### S3 / R2 Mapping

A `ListObjectsV2` response maps directly onto the manifest:

| S3 / R2 field             | Manifest field             |
| ------------------------- | -------------------------- |
| `Contents[].Key`          | `file.key` and `file.path` |
| `Contents[].Size`         | `file.size`                |
| `Contents[].LastModified` | `file.updatedAt`           |
| `Contents[].ETag`         | `file.etag`                |
| `CommonPrefixes[].Prefix` | `folder.path`              |

## Thumbnails

Like [File Thumbnail](/docs/components/file-thumbnail), the component never parses documents and has no renderer dependencies. Generate preview images with whichever stack you already use — EmbedPDF, `@extend-ai/react-docx`, `@extend-ai/react-xlsx`, or a server-side pipeline — then pass the result through `previewImageUrl`. Files without a preview fall back to a generic document tile, or to the node returned by `renderFilePreview`.

One caveat for DOCX: `@extend-ai/react-docx` versions before 0.7.0 rasterize pages in a way that taints the canvas, blocking `toDataURL` export in the browser. On 0.7.0+ the demo generates DOCX thumbnails client-side like the PDFs; on older versions, render DOCX previews live via `renderFilePreview` or generate thumbnail images server-side.

## Lazy Loading

For large buckets, pass `hasChildren: true` on folder entries and provide `loadChildren`. The component fetches a folder's contents the first time it is opened, following `nextCursor` until the listing is exhausted.

```tsx
<FileSystem
  items={rootItems}
  loadChildren={async ({ path, cursor }) =>
    fetch(`/api/files/list?prefix=${path}&cursor=${cursor ?? ""}`).then((r) =>
      r.json()
    )
  }
  getFileUrl={async (file) =>
    `/api/files/sign?key=${encodeURIComponent(file.key ?? file.path)}`
  }
/>
```

## Views

- **Icons** — a thumbnail grid with macOS-style folder glyphs.
- **List** — a hierarchical tree rendered with [`@pierre/trees`](https://github.com/pierredotco/trees), with modified date and size as a trailing column.
- **Columns** — Miller columns with a preview-and-metadata pane for the selected file.
- **Gallery** — a large preview with an information sidebar and a filmstrip of the current folder.

Double-clicking a folder navigates into it. Double-clicking a file (in any view, including the list tree) opens the built-in viewer dialog — PDF, DOCX, PowerPoint (`.pptx`), and XLSX files open in their respective viewers, and images open in an image dialog; other file types open their resolved URL in a new tab. Pass `onFileOpen` to replace this behavior entirely. The registry item depends on the [PDF Viewer](/docs/components/pdf-viewer), [DOCX Viewer](/docs/components/docx-viewer), [PowerPoint Viewer](/docs/components/pptx-viewer), and [Excel Viewer](/docs/components/xlsx-viewer), so installing `@extend/file-system` brings the full preview experience.

The list view tree is derived from file paths, so lazy folders (`hasChildren` without loaded entries) appear there after their contents have been fetched — open them from the icon or column views first, or list them eagerly.

### Keyboard Navigation

- **Grid** — arrow keys move the selection in all four directions, following the rendered grid; Enter opens.
- **List** — full keyboard support from `@pierre/trees` (arrows, type-ahead, expand/collapse); arrow keys move the selection like Finder, and Shift-arrows extend it.
- **Columns** — up/down move within a column, left selects the parent folder, right steps into the selected folder; Enter opens.
- **Gallery** — left/right move through the filmstrip; Enter opens.

Every view is a single tab stop — <kbd>Tab</kbd> lands on the selected item and <kbd>Shift+Tab</kbd> returns to the view switcher, matching the list tree's behavior.

Finder-style shortcuts work everywhere in the component: <kbd>⌘↑</kbd> goes to the enclosing folder, <kbd>⌘↓</kbd> opens the selection, and <kbd>⌘[</kbd> / <kbd>⌘]</kbd> navigate back and forward through history (Ctrl works in place of ⌘).

When the component is narrower than 480px, the toolbar swaps the tabs view switcher for a compact select.

The gallery view embeds the full viewers — PDF, DOCX, PowerPoint, and XLSX files render in their toolbar-less viewer (the XLSX sheet switcher stays), and images scale to fill the stage. While arrow keys are scrubbing the filmstrip the stage shows a spinner; the full viewer mounts once the selection settles, so holding an arrow key stays smooth.

### Multi-Page Thumbnails

Pass `previewImageUrls` (an array of page thumbnails — page counts come from whichever renderer generates them, e.g. EmbedPDF, `@extend-ai/react-docx`, or `@extend-ai/react-xlsx`). Large thumbnails in the column preview show hover pager buttons to step through pages. `previewAspectRatio` on a file controls its thumbnail shape — e.g. natural ratios for images, landscape for spreadsheets.

For long documents, provide only the first page(s) eagerly plus `previewPageCount`, and implement `loadPreviewImageUrl(file, pageIndex)` — the pager renders the remaining pages on demand (the demo renders PDF pages lazily through the shared PDFium thumbnail utility).

## API Reference

### FileSystem

| Prop                  | Type                                                                       | Default   | Required |
| --------------------- | -------------------------------------------------------------------------- | --------- | -------- |
| `items`               | `FileSystemItem[]`                                                         | `-`       | Yes      |
| `className`           | `string`                                                                   | `-`       | No       |
| `title`               | `string`                                                                   | `"Files"` | No       |
| `defaultView`         | `"icons" \| "list" \| "columns" \| "gallery"`                              | `"icons"` | No       |
| `view`                | `FileSystemView`                                                           | `-`       | No       |
| `onViewChange`        | `(view: FileSystemView) => void`                                           | `-`       | No       |
| `defaultPath`         | `string`                                                                   | `""`      | No       |
| `onSelectionChange`   | `(item: FileSystemItem \| null) => void`                                   | `-`       | No       |
| `onFileOpen`          | `(file: FileSystemFileItem, url: string \| null) => void`                  | `-`       | No       |
| `getFileUrl`          | `(file: FileSystemFileItem) => string \| Promise<string>`                  | `-`       | No       |
| `loadChildren`        | `(args: FileSystemLoadChildrenArgs) => Promise<...>`                       | `-`       | No       |
| `loadPreviewImageUrl` | `(file: FileSystemFileItem, pageIndex: number) => Promise<string \| null>` | `-`       | No       |
| `renderFilePreview`   | `(file: FileSystemFileItem) => React.ReactNode`                            | `-`       | No       |

### FileSystemFolderItem

| Prop          | Type       | Default | Required |
| ------------- | ---------- | ------- | -------- |
| `kind`        | `"folder"` | `-`     | Yes      |
| `path`        | `string`   | `-`     | Yes      |
| `name`        | `string`   | `-`     | No       |
| `parentPath`  | `string`   | `-`     | No       |
| `hasChildren` | `boolean`  | `-`     | No       |
| `createdAt`   | `string`   | `-`     | No       |
| `updatedAt`   | `string`   | `-`     | No       |

### FileSystemFileItem

| Prop                 | Type                     | Default | Required |
| -------------------- | ------------------------ | ------- | -------- |
| `kind`               | `"file"`                 | `-`     | Yes      |
| `path`               | `string`                 | `-`     | Yes      |
| `key`                | `string`                 | `path`  | No       |
| `name`               | `string`                 | `-`     | No       |
| `parentPath`         | `string`                 | `-`     | No       |
| `contentType`        | `string`                 | `-`     | No       |
| `size`               | `number`                 | `-`     | No       |
| `createdAt`          | `string`                 | `-`     | No       |
| `updatedAt`          | `string`                 | `-`     | No       |
| `etag`               | `string`                 | `-`     | No       |
| `url`                | `string`                 | `-`     | No       |
| `previewImageUrl`    | `string \| null`         | `-`     | No       |
| `previewImageUrls`   | `string[] \| null`       | `-`     | No       |
| `previewPageCount`   | `number`                 | `-`     | No       |
| `previewAspectRatio` | `number`                 | `-`     | No       |
| `metadata`           | `Record<string, string>` | `-`     | No       |