Files

Preview

Overview

Files is a compound surface for composing file and folder UI from consumer-owned data. Cubitt owns the visual treatment, grid/list layout, controlled selection interactions, inline rename mechanics, item slots, upload affordances, and accessibility details.

Consumers own file schemas, folder hierarchy, navigation, filtering, sorting, URL state, permissions, rename persistence, actions, and upload lifecycle. Folder support is display-only: pass kind: "folder" and handle open/navigation callbacks in your app.

Usage

import {
  Files,
  type FilesItem,
} from "@tilt-legal/cubitt-components/files";

const items: FilesItem[] = [
  { id: "contracts", kind: "folder", name: "Contracts" },
  {
    id: "contract-1",
    kind: "file",
    name: "Client Contract.pdf",
    mediaType: "application/pdf",
    sizeLabel: "612 KB",
  },
];

<Files
  selectedIds={selectedIds}
  onSelectedIdsChange={setSelectedIds}
  onRename={renameItem}
  selectionMode="multiple"
>
  <Files.Grid>
    {items.map((item) => (
      <Files.Item
        item={item}
        key={item.id}
        onOpen={(openedItem) => {
          if (openedItem.kind === "folder") {
            navigateToFolder(openedItem.id);
          }
        }}
      />
    ))}
  </Files.Grid>
</Files>;

The root keeps selection controlled and stores only the transient inline rename draft. Collection components only lay out children, so the consuming app decides which items exist, how they are ordered, which view renders, and how a rename mutation updates source data.

Selection clears from Files.Root when the user clicks anything that is not a selection-preserving surface. Files.Item, Files.Details, Cubitt Toolbar inside the Files root, Base UI portals, and elements marked with data-files-selection-preserve preserve the current selection; blank grid/list/content space clears it. Use data-files-selection-preserve for external toolbar islands that sit outside the Files root.

Use canSelect when some items should be navigable but should not enter selectedIds. For example, a single-file picker can keep files selectable while folders only activate/open:

<Files
  selectedIds={selectedIds}
  onSelectedIdsChange={setSelectedIds}
  canSelect={(item) => item.kind !== "folder"}
  selectionBehavior="toggle"
  selectionMode="single"
>
  {/* collections */}
</Files>

For explorer-style surfaces, leave folders selectable and clear selection in your folder navigation handler. For picker-style surfaces, use canSelect only when a folder should be navigable without becoming a selected value.

For right-click menus, compose the ContextMenu components with useFilesContextMenu so your app owns menu actions while Cubitt keeps item selection semantics consistent.

Files.Item

Contract

FilesItem is the display contract shared by Files.Item, Files.Grid, Files.List, Files.Details, and custom item slots.

type FilesItem<TSource = unknown> = {
  id: string;
  kind: "file" | "folder";
  name: string;
  size?: number;
  mediaType?: string;
  sizeLabel?: string;
  description?: string;
  badge?: ReactNode;
  icon?: ReactNode;
  thumbnailUrl?: string;
  state?: "default" | "loading" | "uploading" | "error";
  progress?: number;
  disabled?: boolean;
  source?: TSource;
};

source is a passthrough for consumer data. Cubitt does not read it. Use size when Cubitt should calculate multi-file details totals; use sizeLabel when the consuming app already has a formatted display value.

Use state: "loading" for skeleton placeholders, state: "uploading" with progress for upload display, and state: "error" for failed upload display. These states are visual only; the consuming app still owns retry, cancel, persistence, and upload queue state.

Composition

Files.Item renders one display-only FilesItem. Default grid and list rendering is built from the same item slots consumers can use when composing custom item content.

The same item context powers the slots used by grid rows, list rows, and details surfaces.

Use badge for small icon indicators, such as shared, reviewed, or confidential states. If an app needs explanatory labels, keep that label in app-owned data and compose a custom Files.ItemBadge slot with the right accessible label or tooltip.

Use Files.FolderIcon or the named FilesFolderIcon export when surrounding file UI, such as toolbar breadcrumbs, should use the same custom folder artwork as Files.Item and Files.Details.

API Reference

Files

Root provider for controlled selection and shared item interaction state.

Also accepts standard div props.

Files.Content

Also accepts standard div props.

Files.Item

Files.Item must be rendered inside Files.Grid or Files.List so it can inherit the active layout.

Also accepts standard button props.

Files.Item Slots

Files.UploadButton

Stateless file picker action. It does not create upload queues or persist files.

Also accepts Button props except onChange and onClick.

Types And Hooks

Components

Examples