File List Gallery View
Finder's gallery view: a large preview over a strip of thumbnails, with the file's information beside it.
@cupertinoui-pro/file-list-gallery-viewCupertinoUI Pro"use client"
import * as React from "react"
import { CircleEllipsisIcon, RotateCcwSquareIcon } from "lucide-react"
import type { FileNode } from "@/registry/macos/lib/file-tree"
import {
FileListGalleryAction,
FileListGalleryView,
} from "@/components/ui/file-list-gallery-view"
// `created`, `modified` and the `info` rows fill in the information.
const initialFiles: FileNode[] = [
{
name: "Drift Light.webp",
kind: "WebP Image",
size: "52 KB",
thumbnail: "/wallpapers/drift-light.webp",
created: "27. October 2026 at 09:41",
modified: "27. October 2026 at 09:41",
info: { Dimensions: "2560×2560" },
},
{
name: "Drift Dark.webp",
kind: "WebP Image",
size: "44 KB",
thumbnail: "/wallpapers/drift-dark.webp",
created: "27. October 2026 at 09:42",
modified: "27. October 2026 at 09:42",
info: { Dimensions: "2560×2560" },
tag: "purple",
},
{ name: "Design", kind: "Folder", modified: "21. October 2026 at 15:42", children: [] },
{ name: "Roadmap.key", kind: "Keynote", size: "2,4 MB", modified: "8. October 2026 at 10:15" },
]
// The arrow keys step through the strip; double-click a folder to go into
// it and ⌘↑ to come back. Drag a thumbnail onto the folder to move it.
export default function FileListGalleryViewDemo() {
const [files, setFiles] = React.useState(initialFiles)
return (
<div className="flex h-[420px] w-full max-w-3xl overflow-hidden rounded-[12px] bg-mac-content shadow-[0_0_0_1px_var(--mac-grid)]">
<FileListGalleryView
files={files}
onFilesChange={setFiles}
renderActions={(file) => (
<>
{file.thumbnail && (
<FileListGalleryAction>
<RotateCcwSquareIcon strokeWidth={1.5} />
Rotate Left
</FileListGalleryAction>
)}
<FileListGalleryAction>
<CircleEllipsisIcon strokeWidth={1.5} />
More…
</FileListGalleryAction>
</>
)}
className="flex-1"
/>
</div>
)
}Installation
pnpm dlx shadcn@latest add @cupertinoui-pro/file-list-gallery-viewPart of CupertinoUI Pro: the CLI installs it with your license key, once the @cupertinoui-pro registry is in components.json.
Usage
import { FileListGalleryView } from "@/components/ui/file-list-gallery-view"
<FileListGalleryView files={files} onFilesChange={setFiles} />A large preview of the selected file over a strip of thumbnails, with its information beside it, as in Finder's gallery view. The first file starts out selected and its name floats over its thumbnail.
The preview is the file's thumbnail as large as fits, or its icon; renderPreview draws something else, such as a video or a PDF.
The information shows the name, kind and size, then Created, Modified and the file's info rows, then its tag. renderActions adds quick actions under it (FileListGalleryAction is the icon-over-label button), renderInfo replaces it and info={false} hides it.
Left and right step through the strip, with Shift they extend the selection. Double-click a folder (or ⌘↓) to go into it and ⌘↑ to go back out. With onFilesChange, drag a thumbnail onto a folder to move it, and use the same right-click menu and keys as the other file lists.
API Reference
Every part forwards the props of the underlying element. The props below are the ones CupertinoUI adds or changes.
FileListGalleryView
| Prop | Type | Description |
|---|---|---|
files | FileNode[] | The tree. The view shows one folder of it at a time. |
defaultFolder | string | nullDefault: null | The key of the folder shown first; null is the top of the tree. |
folder | string | null | The folder shown, controlled. Update it from onFolderChange. |
onFolderChange | (folder: string | null) => void | Called when a folder is opened, or ⌘↑ goes back up. |
multiple | booleanDefault: true | Lets people select several files with Shift and ⌘. false allows one. |
defaultSelected / selected | string[] | The keys of the selected files, uncontrolled or controlled. |
onSelectedChange | (keys: string[], files: FileNode[]) => void | Called when the selection changes. |
renderIcon | (file: FileNode) => ReactNode | The icon of a file without a thumbnail, drawn 64px large. Defaults to a folder or a document. |
onFilesChange | (files: FileNode[], change: FileChange) => void | Turns on editing: moving, Move to Trash, Rename, Duplicate, New Folder and tags. Gets the new tree to store, and what changed. |
onOpen | (file: FileNode, key: string) => void | Called when a file is opened: double-clicked, or ⌘O or ⌘↓. Folders open in the view. |
menuItems | (files: FileNode[], keys: string[]) => ReactNode | More ContextMenuItems for the right-click menu, after Finder's own. |
renderPreview | (file: FileNode) => ReactNode | The large preview. Defaults to the thumbnail, or a 256px icon. |
info | booleanDefault: true | Shows the information beside the preview. |
renderInfo | (file: FileNode, key: string) => ReactNode | Replaces the information; FileListGalleryInfo is the default. |
renderActions | (file: FileNode) => ReactNode | Quick actions under the information, as FileListGalleryActions. |
className | string | Extra classes, merged with the component's own. |
FileListGalleryInfo
| Prop | Type | Description |
|---|---|---|
file | FileNode | The file to describe. |
actions | ReactNode | Quick actions at the bottom. |
className | string | Extra classes, merged with the component's own. |
FileListGalleryAction
A quick action: an icon over a label, as a button.
| Prop | Type | Description |
|---|---|---|
className | string | Extra classes, merged with the component's own. |

