Documents
Headless compound that fetches a business's uploaded documents and exposes a slot for every cell — description, file name, date, source, status, and type. Built-in interactions: a drag-and-drop upload zone with per-file queue chips, inline delete confirmation, a per-row actions menu with preview/download/delete actions, and a full-screen lightbox. All four states (loading, error, empty, success) are covered by state-gate wrappers; compose the parts you need and use asChild to hand rendering to your own elements.
Anatomy
Import the primitive and compose the parts you need.
<Documents.Root documentType={type} onDelete={handleDelete} onDownload={handleDownload}> <Documents.Success> {/* Drag-and-drop upload + per-file queue chips */} <Documents.UploadDropzone /> <Documents.UploadItems> <Documents.UploadItem> <Documents.UploadItemName /> <Documents.UploadItemMeta /> <Documents.UploadItemUploading>…</Documents.UploadItemUploading> <Documents.UploadItemSuccess>…</Documents.UploadItemSuccess> <Documents.UploadItemError> <Documents.UploadItemErrorMessage /> <Documents.UploadItemDismiss /> </Documents.UploadItemError> </Documents.UploadItem> </Documents.UploadItems> <Documents.Rows> <Documents.Row> <Documents.Description /> <Documents.FileName /> <Documents.Date /> <Documents.Source /> <Documents.Status /> <Documents.Type /> <Documents.RowActions /> <Documents.ViewDetailsAction /> <Documents.PreviewAction /> <Documents.DownloadAction /> <Documents.DeleteAction /> {/* Inline delete confirm */} <Documents.DeleteConfirm> <Documents.DeleteTitle /> <Documents.DeleteBody /> <Documents.ConfirmDelete /> <Documents.CancelDelete /> </Documents.DeleteConfirm> {/* Full-screen lightbox */} <Documents.Lightbox> <Documents.PreviewImage> <Documents.LightboxImage /> </Documents.PreviewImage> <Documents.PreviewPdf> <Documents.LightboxFrame /> </Documents.PreviewPdf> <Documents.LightboxClose /> </Documents.Lightbox> </Documents.Row> </Documents.Rows> </Documents.Success> <Documents.Loading>…</Documents.Loading> <Documents.Empty>No documents yet.</Documents.Empty> <Documents.Error> <Documents.ErrorMessage /> <Documents.Retry>Try Again</Documents.Retry> </Documents.Error></Documents.Root>Required scopes
The access token used by AssetProvider must include these scopes for this primitive to fetch data successfully:
document:readdocument:createdocument:delete
API reference
Root props
| Prop | Type | Default | Description |
|---|---|---|---|
documentType | DocumentType | — | Filter by type (receipt / statement / payroll / bill / mileage / other). Passed to the API. |
transactionId | string | — | Filter to documents linked to a transaction. Passed to the API. |
externalAccountId | string | — | Narrow to documents belonging to one external account. The list endpoint takes no such filter, so this is applied client-side over the fetched page — which also means it narrows a `documents` override. Matches either external_account_id or external_account_ids. |
onUpload | (type?: DocumentType) => void | — | Provide to handle uploads yourself — the built-in dropzone upload + queue is skipped. |
onDelete | (documentId: string) => void | — | Provide to handle deletion yourself — the built-in delete mutation is skipped. |
onDownload | (documentId: string) => void | — | Provide to handle download yourself — the built-in signed-URL fetch + download is skipped. |
onViewDetails | (documentId: string) => void | — | Called when the user picks View details on a row — render your detail view (e.g. DocumentDetails) for that document. Only statements with a detail view show the action. Without the callback, ViewDetailsAction renders nothing. |
maxFileSize | number | — | Per-file size ceiling in bytes for the dropzone. Defaults to DEFAULT_MAX_FILE_SIZE (25 MB). |
documents | DocumentPublic[] | — | Override the fetched list (skips the API call). Storybook/tests. |
state | "loading" | "error" | "empty" | — | Force a specific state for testing. |
uploadItems | UploadItem[] | — | Seed the upload queue (no real uploads run). Storybook/tests. |
confirmingRowId | string | — | Seed the delete-confirm panel for this row's document id. Storybook/tests. |
previewRowId | string | — | Seed the lightbox open for this row's document id. Storybook/tests. |
signedUrlOverride | string | — | Use this URL for the preview lightbox, skipping the signed-URL fetch (keeps stories offline). |
childrenrequired | ReactNode | — | Compound parts. |
Parts
Container
Always rendered. Fetches documents, owns UI state, and provides context.
| Part | Description |
|---|---|
Documents.Root | Owns fetching, filters, upload/delete/download actions, and the open/confirming/preview row state. |
Success
Renders when at least one document is available.
| Part | Description |
|---|---|
Documents.Success | State wrapper. Compose the list inside. |
Documents.UploadDropzoneasChild? | Drag-and-drop surface — wires the drop to addFiles and sets data-dragging. (Browse + hidden input live in the styled layer.) |
Documents.UploadItems | Iterates the per-file upload queue, providing each item's context. |
Documents.UploadItemasChild? | Chip container for one queued file. Sets data-status. |
Documents.UploadItemNameasChild? | The file name. |
Documents.UploadItemMetaasChild?, format? | Extension + size, e.g. "PDF · 84 KB". |
Documents.UploadItemUploading / Success / Error | Gates that render while the item is uploading / succeeded / errored. |
Documents.UploadItemErrorMessageasChild? | Error copy (e.g. "File is over size limit", "Already uploaded"). Renders only on error. |
Documents.UploadItemDismissasChild? | Button that removes the item from the queue. |
Documents.Rows | Iterates each document, providing a per-row context. |
Documents.RowasChild? | Per-row wrapper. Sets data-status and data-type. |
Documents.DescriptionasChild? | The description. |
Documents.FileNameasChild? | The uploaded file name. |
Documents.DateasChild?, format? | Created date, "Apr 30, 2026" (UTC). |
Documents.SourceasChild?, format? | Source label — Upload / Email forward / Integration. |
Documents.StatusasChild?, format? | Status label + data-status tone. The raw API statuses collapse to 5 display states: Processed / Processing / Pending / Needs Attention / Failed. |
Documents.TypeasChild?, format? | Type label + data-type (receipt / statement / payroll / bill / mileage / other). |
Documents.RowActionsasChild? | Wrapper for the kebab trigger; compose Preview/Download/Delete inside your menu. |
Documents.ViewDetailsActionasChild? | Opens the document's detail view via the Root's onViewDetails. Only shows for statements with a detail view and a host-provided callback. |
Documents.PreviewActionasChild? | Opens the lightbox preview. Image filenames render as images; extensionless or non-image filenames use the frame preview. |
Documents.DownloadActionasChild? | Downloads the document (signed URL → browser download, or onDownload). |
Documents.DeleteActionasChild? | Opens the inline delete-confirm panel for the row. |
Documents.PreviewImage / PreviewPdf | Gates — render children when the preview is an image / the frame preview. |
Documents.DeleteConfirmasChild? | Gate — renders the inline confirm panel when the row is confirming. |
Documents.DeleteTitle / DeleteBodyasChild? | The confirm title (document description) and body copy. |
Documents.ConfirmDelete / CancelDeleteasChild? | Buttons that run the delete or cancel it. |
Documents.Lightbox | Gate — renders the full-screen preview when the row is the preview row. |
Documents.LightboxImage / LightboxFrameasChild? | Full-size image / PDF, with the signed URL as src. |
Documents.LightboxCloseasChild? | Button that closes the lightbox. |
Loading
Renders while the fetch is in flight.
| Part | Description |
|---|---|
Documents.Loading | State wrapper. Render skeleton rows inside. |
Empty
Renders when no documents are found.
| Part | Description |
|---|---|
Documents.Empty | State wrapper. Render an empty-state message inside. |
Error
Renders on fetch error.
| Part | Description |
|---|---|
Documents.Error | State wrapper. Compose the error UI inside. |
Documents.ErrorMessageasChild? | Renders the error message string. |
Documents.RetryasChild? | Button that re-runs the fetch. |
Hooks
| Part | Description |
|---|---|
useDocuments() | Top-level context (documents, state, actions, confirming/preview ids). |
useDocumentsRow() | The current row context (document, date, source, status, type). |
Documents.useUploadItem() | The current upload-queue item, inside UploadItems. |