File List Columns

A plain list as used by Finder's column view, with focused and unfocused selection.

@cupertinoui-pro/file-list-columnsCupertinoUI Pro

Installation

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

Part of CupertinoUI Pro: the CLI installs it with your license key, once the @cupertinoui-pro registry is in components.json.

Usage

import { FileListColumns } from "@/components/ui/file-list-columns"
import type { FileNode } from "@/lib/file-tree"

const files: FileNode[] = [
  {
    name: "Documents",
    children: [{ name: "Notes.txt", kind: "Plain Text", size: "4 KB" }],
  },
]

<FileListColumns files={files} defaultSelected={["Documents/Notes.txt"]} />
files is plain JSON, the same structure FileListTable takes, so both can show one tree. Selecting a folder opens its contents in a new column; the arrow keys move up and down a column and in and out of folders.
Like Finder, drag over items to select several in one column, from an item or from empty space; Shift-click selects a range and ⌘-click adds or removes an item. With several selected, no further column or preview opens.
With onFilesChange, drag selected items onto a folder, or into another column, to move them there; the browser follows them. Escape cancels, and ⌘⌫ deletes the selection.
Right-click for Finder's menu: Open, Move to Trash, Rename, Duplicate, Copy and the tag colors; on empty space, New Folder. Renaming edits the name in place (Return also starts it), ⌘D duplicates and ⇧⌘N makes a folder. Without onFilesChange the menu only opens and copies.
Expanded folders and the selection are keys: the ids from the top of the tree down to the file, joined by "/", e.g. "Invoices/2026/October.pdf".
Columns open 244px wide, like Finder's; set columnWidth to change that. Drag a column's right edge to resize it. When the columns don't fit, the view scrolls and keeps the last column in view.
A selected file shows Finder's preview pane after the last column (FileListColumnsPreview): its thumbnail, or a large document icon labeled with its extension (with a zipper for archives), then its name, kind and size, Created, Modified and info rows, and tags. The picture shrinks with the pane's height and stays centered above the name. Pass renderPreview to show something else, or compose FileListColumnsPreview with your own artwork and actions.

Examples

Composition

Without files, FileListColumns is a single column that you fill with items, and you decide what the next column shows.

API Reference

Every part forwards the props of the underlying element. The props below are the ones CupertinoUI adds or changes.

FileNode

One file or folder in files: plain JSON, the same for every file list. Import the type from @/lib/file-tree.

PropTypeDescription
namestringThe file name.
idstringUnique among its siblings, for keys; defaults to the name. Can't contain "/".
childrenFileNode[]Makes it a folder; folders nest to any depth. Use [] for an empty folder.
thumbnailstringAn image URL shown instead of the icon in the icon and gallery views, and as the preview.
kind / size / created / modifiedstringShown as they are, so format them the way you want them displayed.
infoRecord<string, string>More Information rows for the column and gallery previews, e.g. { Dimensions: "2007×2853" }.
iconstringA hint for renderIcon, e.g. "image" or "movie".
tagstringA Finder tag color: "red", "orange", "yellow", "green", "blue", "purple" or "gray".
onOpen(file: FileNode) => voidCalled when this file or folder is opened: double-clicked, or ⌘O.

FileListColumns

PropTypeDescription
filesFileNode[]The tree to browse. Leave it out to use FileListColumns as a single column.
multipleboolean
Default: true
Lets people select several items in a column: drag over them, Shift-click a range, ⌘-click single items, Shift with the arrow keys or ⌘A. false allows one item.
defaultSelectedstring[]The keys of the files that start selected, all in one folder; the folders above them are open.
selectedstring[]The keys of the selected files, controlled. Update it from onSelectedChange.
onSelectedChange(keys: string[], files: FileNode[]) => voidCalled when the selection changes, with the keys and files in order.
renderIcon(file: FileNode) => ReactNodeThe 16px icon of a file. Defaults to a folder or a document.
renderPreview(file: FileNode) => ReactNodeShown after the last column when one file is selected, in place of FileListColumnsPreview.
columnWidthnumber
Default: 244
The width columns open at, in pixels. Columns can then be resized by dragging their right edge.
onFilesChange(files: FileNode[], change: FileChange) => voidTurns on editing: dragging selected items onto a folder moves them, ⌘⌫ deletes them. Gets the new tree to store, and what changed: { action: "move", keys, to } or { action: "delete", keys }.
onOpen(file: FileNode, key: string) => voidCalled when a file is opened: double-clicked, or ⌘O or ⌘↓ on the selection. Use it to show the file, e.g. in a new window.
menuItems(files: FileNode[], keys: string[]) => ReactNodeMore ContextMenuItems for the right-click menu, after Finder's own.
activeboolean
Default: false
Without files: the column with keyboard focus, whose selection is blue; others are grey.
classNamestringExtra classes, merged with the component's own.

FileListColumnsItem

PropTypeDescription
selectedboolean
Default: false
Marks the selected item.
renderReactElementRender a link or button with the item's styles.

FileListColumnsItemLabel / FileListColumnsItemChevron

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

FileListColumnsPreview

The preview pane: the default for a selected file.

PropTypeDescription
fileFileNodeThe file to preview.
artworkReactNodeReplaces the picture. Defaults to the thumbnail, or a large document icon.
actionsReactNodeQuick actions at the bottom, as FileListColumnsPreviewActions.
classNamestringExtra classes, merged with the component's own.

FileListColumnsPreviewAction

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

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