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 rendering, 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", itemCount: 4 },
  {
    id: "contract-1",
    kind: "file",
    name: "Client Contract.pdf",
    mimeType: "application/pdf",
    size: 612_000,
    createdBy: "Ava Johnson",
    updatedAt: "2026-04-18",
  },
];

<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, and Files.Details.

type FilesItem = {
  id: string;
  kind: "file" | "folder";
  name: string;
  size?: number;
  itemCount?: number;
  mimeType?: string;
  createdBy?: ReactNode;
  createdAt?: Date | number | string;
  updatedAt?: Date | number | string;
  badge?: ReactNode;
  icon?: ReactNode;
  status?:
    | { type: "loading" }
    | { type: "uploading"; progress?: number }
    | { type: "error"; message?: ReactNode };
  disabled?: boolean;
};

Use size for file byte size. Cubitt formats it as KB, MB, or GB. Use itemCount for folders; it renders in the Size column as an item count rather than bytes.

Use mimeType for file type and icon derivation. If icon is provided, it overrides the derived file/folder icon.

Use createdBy, createdAt, and updatedAt for first-class list/details metadata. Files.List keeps configured columns stable when values are missing; the default headers are Name, Type, Size, Created by, Created, and Updated. Consumers can still extend FilesItem with app-owned fields:

type MatterFileItem = FilesItem & {
  matterId: string;
  parentId: string | null;
  workflowStatus: "Draft" | "Reviewed" | "Filed";
};

Use status: { type: "loading" } for skeleton placeholders, status: { type: "uploading", progress } for upload display, and status: { type: "error", message } for failed upload display. These statuses are visual only; the consuming app still owns retry, cancel, persistence, and upload queue state. Uploading items with missing or zero progress use only the indeterminate icon. Positive progress and failures render after a middle dot in the list Name cell.

Rendering

Files.Item renders one display-only FilesItem. Grid and list rows are owned by Cubitt and use the item data to render selection, icon, name, size, type, metadata, badge, and status affordances.

Use badge for small icon indicators, such as shared, reviewed, or confidential states.

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 through the default root.

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.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