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

Installation

pnpm dlx shadcn@latest add @cupertinoui-pro/file-list-gallery-view

Part 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

PropTypeDescription
filesFileNode[]The tree. The view shows one folder of it at a time.
defaultFolderstring | null
Default: null
The key of the folder shown first; null is the top of the tree.
folderstring | nullThe folder shown, controlled. Update it from onFolderChange.
onFolderChange(folder: string | null) => voidCalled when a folder is opened, or ⌘↑ goes back up.
multipleboolean
Default: true
Lets people select several files with Shift and ⌘. false allows one.
defaultSelected / selectedstring[]The keys of the selected files, uncontrolled or controlled.
onSelectedChange(keys: string[], files: FileNode[]) => voidCalled when the selection changes.
renderIcon(file: FileNode) => ReactNodeThe icon of a file without a thumbnail, drawn 64px large. Defaults to a folder or a document.
onFilesChange(files: FileNode[], change: FileChange) => voidTurns 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) => voidCalled when a file is opened: double-clicked, or ⌘O or ⌘↓. Folders open in the view.
menuItems(files: FileNode[], keys: string[]) => ReactNodeMore ContextMenuItems for the right-click menu, after Finder's own.
renderPreview(file: FileNode) => ReactNodeThe large preview. Defaults to the thumbnail, or a 256px icon.
infoboolean
Default: true
Shows the information beside the preview.
renderInfo(file: FileNode, key: string) => ReactNodeReplaces the information; FileListGalleryInfo is the default.
renderActions(file: FileNode) => ReactNodeQuick actions under the information, as FileListGalleryActions.
classNamestringExtra classes, merged with the component's own.

FileListGalleryInfo

PropTypeDescription
fileFileNodeThe file to describe.
actionsReactNodeQuick actions at the bottom.
classNamestringExtra classes, merged with the component's own.

FileListGalleryAction

A quick action: an icon over a label, as a button.

PropTypeDescription
classNamestringExtra classes, merged with the component's own.