Headless / Files & documents

Preview files

A keyboard-accessible file viewer shared by every family that shows files: a file browser, an upload queue, chat attachments. It takes a list of preview items (id, name, media type, nullable url), opens a modal on one, steps between them and draws each with a native stage: image with zoom, audio, video, a sandboxed frame for PDF, highlighted text, CSV. A format it cannot draw gets an honest fallback, never an endless spinner.

39 public parts · 2examples

@slices.sh/quick-look/headlessView as Markdown ↗

Your design. Our behavior.

Explore the tree to see what each part controls. Gates reveal the relevant state; roots outline their scope.

Behavior / inputGateGenericRenderer · not headlessScope

COMPONENT ANATOMYHover · focus · tap

Preview files

ONE POSSIBLE DESIGNStatic preview

QuickLook.Root · Generic

QuickLook.RootThe selection, and a trigger per item (itemId) that opens the viewer on it.

Installation

Choose what your component needs. Run these commands in an initialized Next.js app.

Before you start

The steps below run in a Next.js app with shadcn set up (it has a components.json). In an existing Next.js app, such as one from create-next-app, set shadcn up first:

npx shadcn@latest init -t next -b base -p nova

Or start fresh: the slices CLI creates the app and sets it up.

npx slices.sh install

Install the headless library

npm

Add the React parts to your app, then compose them with your own elements.

npm install @slices.sh/quick-look@^0.1.2

Import from @slices.sh/quick-look/headless.

These parts run locally. No service installation or provisioning is needed.

Optional: XLSX document stage

Before you start

The steps below run in a Next.js app with shadcn set up (it has a components.json). In an existing Next.js app, such as one from create-next-app, set shadcn up first:

npx shadcn@latest init -t next -b base -p nova

Or start fresh: the slices CLI creates the app and sets it up.

npx slices.sh install

Install the service registry

Adds services/index.ts, which import "@/services" loads. A provider setup writes the same file, so skip this if your app has one.

npx add services

Install the headless library

npm

Add the React parts to your app, then compose them with your own elements.

npm install @slices.sh/file-storage

Import from @slices.sh/file-storage/headless/document-xlsx.

Install the service

Connect the parts to a provider. Skip this step if this service is already configured in your app.

Provider

npx add file-storage.local

Adds service configuration and API routes to your app, with the provider dependencies. For a headless composition, add import "@/services" after "use client".

The slices CLI installs the service and provisions its required resources in one command.

Provider setup notes

Add .data/ to .gitignore: the bytes and the index live there.
This store lives on one disk. A serverless deployment loses the files between requests, so deploy with @slices.sh/file-storage.s3.
A screen works in a bucket, a private corner of the config ("files" by default). The config lists the ones its screens work in (`buckets`, which installs grow); list more, or a prefix such as "playground/", in `buckets` in services/file-storage/rules.ts. Any other is not-found.
Set maxUploadBytes and accept in services/file-storage/default.config.ts: nothing is capped until you do.

Start small

Parts bring the behavior. Use their default elements, or supply your own with render.

example.tsx

"use client"import { QuickLook } from "@slices.sh/quick-look/headless"import type { PreviewItem } from "@slices.sh/quick-look/services/types"export function Example({ items }: { items: PreviewItem[] }) {  return (    <QuickLook.Root items={items}>      {items.map((item) => (        <QuickLook.Trigger key={item.id} itemId={item.id}>          {item.name}        </QuickLook.Trigger>      ))}      <QuickLook.Content>        <QuickLook.Title>File preview</QuickLook.Title>        <QuickLook.Selected>          {({ item }) => (            <QuickLook.StageRoot item={item}>              <QuickLook.Image />              <QuickLook.Unavailable>                No preview available.              </QuickLook.Unavailable>            </QuickLook.StageRoot>          )}        </QuickLook.Selected>        <QuickLook.Close>Close</QuickLook.Close>      </QuickLook.Content>    </QuickLook.Root>  )}

Supply items with id, name, mediaType and url. The dialog needs no storage service.

API reference

Every public part used by this experience is listed below. Gates render children without adding an element. Element parts accept native element props and render; function children receive the state declared in their props. Scopes provide context rather than a visual element.

QuickLook.Rootscope · Generic

The selection, and a trigger per item (itemId) that opens the viewer on it.

Props

4 documented props

QuickLook.Root props
Prop	Type	Default
`items`Required	`readonly PreviewItem[]`	`—`
`enabled` Quick look has no service to be missing, so nothing here throws. `false` is off: the root renders nothing, and so does every part of it. Anything else leaves it on.	`Enabled`	`—`
`config` Accepted so every root takes the same props: quick look has no configs.	`string`	`—`
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/root.tsx

QuickLook.Contentcontent · Generic · <div>

The modal content with its motion surface, its title and description for assistive technology, and closing it. Focus, Escape and dismissal are the dialog primitive's.

Required scope

QuickLook.Content requires QuickLook.Root.

Props

2 documented props · Native <div> attributes supported

QuickLook.Content props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/content.tsx

QuickLook.Titlecontent · Generic · <h2>

The modal content with its motion surface, its title and description for assistive technology, and closing it. Focus, Escape and dismissal are the dialog primitive's.

Props

2 documented props · Native <h2> attributes supported

QuickLook.Title props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/title.tsx

QuickLook.Descriptioncontent · Generic · <p>

The modal content with its motion surface, its title and description for assistive technology, and closing it. Focus, Escape and dismissal are the dialog primitive's.

Props

2 documented props · Native <p> attributes supported

QuickLook.Description props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/description.tsx

QuickLook.Closeaction · Generic · <button>

The modal content with its motion surface, its title and description for assistive technology, and closing it. Focus, Escape and dismissal are the dialog primitive's.

Props

2 documented props · Native <button> attributes supported

QuickLook.Close props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/close.tsx

QuickLook.Selectedgate · Generic

Selected renders with { item } while a file is open. StageRoot takes that item (and text, pdf to allow those reads) and resets its image, error and load state by file identity; keep it mounted while the item changes so the navigation buttons keep focus.

Required scope

QuickLook.Selected requires QuickLook.Root.

Props

1 documented props

QuickLook.Selected props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { item: PreviewItem }) => ReactNode)`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/selected.tsx

QuickLook.StageRootscope · Generic

Reset per-file state without replacing focused navigation controls.

Props

4 documented props

QuickLook.StageRoot props
Prop	Type	Default
`item`Required	`PreviewItem`	`—`
`text`	`boolean`	`false`
`pdf`	`boolean`	`false`
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/stage-root.tsx

QuickLook.Previousaction · Generic · <button>

Previous and next through the items, disabled at the ends, and the page with { index, total }.

Required scope

QuickLook.Previous requires QuickLook.Root.

Props

2 documented props · Native <button> attributes supported

QuickLook.Previous props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/previous.tsx

QuickLook.Pagecontent · Generic · <span>

Previous and next through the items, disabled at the ends, and the page with { index, total }.

Required scope

QuickLook.Page requires QuickLook.Root.

Props

2 documented props · Native <span> attributes supported

QuickLook.Page props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { index: number; total: number }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/page.tsx

QuickLook.Nextaction · Generic · <button>

Previous and next through the items, disabled at the ends, and the page with { index, total }.

Required scope

QuickLook.Next requires QuickLook.Root.

Props

2 documented props · Native <button> attributes supported

QuickLook.Next props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/next.tsx

QuickLook.ZoomOutaction · Generic · <button>

Zoom in, zoom out and fit, with Fit giving { percent }. They render only on an image stage.

Required scope

QuickLook.ZoomOut requires QuickLook.StageRoot.

Props

2 documented props · Native <button> attributes supported

QuickLook.ZoomOut props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/zoom-out.tsx

QuickLook.Fitaction · Generic · <button>

Zoom in, zoom out and fit, with Fit giving { percent }. They render only on an image stage.

Required scope

QuickLook.Fit requires QuickLook.StageRoot.

Props

2 documented props · Native <button> attributes supported

QuickLook.Fit props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { percent: number }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/fit.tsx

QuickLook.ZoomInaction · Generic · <button>

Zoom in, zoom out and fit, with Fit giving { percent }. They render only on an image stage.

Required scope

QuickLook.ZoomIn requires QuickLook.StageRoot.

Props

2 documented props · Native <button> attributes supported

QuickLook.ZoomIn props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/zoom-in.tsx

QuickLook.Imagecontent · Generic · <img>

Each renders only for its kind of file once its address is known: an image, audio and video with native controls, a sandboxed frame for a PDF, text as code or markdown (Text kind), and the first rows of a CSV with whether they were cut short.

Capability: previews

Required scope

QuickLook.Image requires QuickLook.StageRoot.

Props

2 documented props · Native <img> attributes supported

QuickLook.Image props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/image.tsx

QuickLook.Linkcontent · Generic · <a>

Loading while text is being read; Unavailable when there is no address, the kind cannot be drawn, or the load failed; and Link, which opens the file in a new tab only for an http(s) or same-origin address.

Required scope

QuickLook.Link requires QuickLook.StageRoot.

Props

2 documented props · Native <a> attributes supported

QuickLook.Link props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/link.tsx

QuickLook.Triggeraction · Generic · <button>

The selection, and a trigger per item (itemId) that opens the viewer on it.

Required scope

QuickLook.Trigger requires QuickLook.Root.

Props

3 documented props · Native <button> attributes supported

QuickLook.Trigger props
Prop	Type	Default
`itemId`Required	`string`	`—`
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/trigger.tsx

QuickLook.Framecontent · Generic · <iframe>

Capability: previews

Required scope

QuickLook.Frame requires QuickLook.StageRoot.

Props

2 documented props · Native <iframe> attributes supported

QuickLook.Frame props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/frame.tsx

QuickLook.Audiocontent · Generic · <audio>

Capability: previews

Required scope

QuickLook.Audio requires QuickLook.StageRoot.

Props

2 documented props · Native <audio> attributes supported

QuickLook.Audio props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/audio.tsx

QuickLook.Videocontent · Generic · <video>

Capability: previews

Required scope

QuickLook.Video requires QuickLook.StageRoot.

Props

2 documented props · Native <video> attributes supported

QuickLook.Video props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/video.tsx

QuickLook.Csvgate · Generic

Capability: previews

Required scope

QuickLook.Csv requires QuickLook.StageRoot.

Props

1 documented props

QuickLook.Csv props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: CsvPreview) => ReactNode)`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/csv.tsx

QuickLook.Textgate · Generic

Capability: previews

Required scope

QuickLook.Text requires QuickLook.StageRoot.

Props

2 documented props

QuickLook.Text props
Prop	Type	Default
`kind`Required	`"code" \| "markdown" \| "csv"`	`—`
`children` Content rendered inside this part.	`ReactNode \| ((state: { text: string; name: string; mediaType: string }) => ReactNode)`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/text.tsx

QuickLook.Loadinggate · Generic

Required scope

QuickLook.Loading requires QuickLook.StageRoot.

Props

1 documented props

QuickLook.Loading props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/loading.tsx

QuickLook.Unavailablegate · Generic

Required scope

QuickLook.Unavailable requires QuickLook.StageRoot.

Props

1 documented props

QuickLook.Unavailable props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/quick-look/src/headless/unavailable.tsx

FilePreview.Rootscope

Root for a folder's rows (what is on screen first, then what a tree or column has read). UploadsRoot, inside Upload.Root, for the files in a queue, with local previews until they have landed.

Props

1 documented props

FilePreview.Root props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-preview/root.tsx

FilePreview.Openaction · <button>

Open behaves as Files.Open on a folder and as a viewer trigger on a file. Trigger renders only for a file, for an embedded list that should not navigate folders. UploadTrigger opens a queued file, and is disabled until there is a stored record or a local preview.

Capability: previews

Required scope

FilePreview.Open requires Files.Entries.

Props

2 documented props · Native <button> attributes supported

FilePreview.Open props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-preview/open.tsx

FilePreview.Triggeraction · <button>

File-only trigger, so an embedded list need not invent folder navigation.

Capability: previews

Required scope

FilePreview.Trigger requires Files.Entries.

Props

2 documented props · Native <button> attributes supported

FilePreview.Trigger props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-preview/trigger.tsx

FilePreview.Downloadcontent · <a>

A link to the file in view, signed for saving with its own name, or the local copy of a file not yet uploaded. data-pending until the address arrives; nothing while no file is open.

Required scope

FilePreview.Download requires a preview root.

Props

2 documented props · Native <a> attributes supported

FilePreview.Download props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-preview/download.tsx

FilePreview.UploadsRootscope

Root for a folder's rows (what is on screen first, then what a tree or column has read). UploadsRoot, inside Upload.Root, for the files in a queue, with local previews until they have landed.

Required scope

FilePreview.UploadsRoot requires Upload.Root.

Props

1 documented props

FilePreview.UploadsRoot props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-preview/uploads-root.tsx

FilePreview.UploadTriggeraction · <button>

Capability: previews

Required scope

FilePreview.UploadTrigger requires Upload.Uploads.

Props

2 documented props · Native <button> attributes supported

FilePreview.UploadTrigger props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-preview/upload-trigger.tsx

FileDocument.Rootscope

Root holds the read. Boundary is an error boundary around a lazy viewer: a chunk that fails to load or a parser that throws renders fallback, and resetKey (the bytes) clears it for the next file.

Required scope

FileDocument.Root requires QuickLook.StageRoot.

Props

1 documented props

FileDocument.Root props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-document/root.tsx

FileDocument.Formatsgate

Renders its children when the stage's file is one of formats ("pdf", "docx", "xlsx", "pptx"), or with except, when it is none of them. A file of unknown format is never one of them.

Capability: documents (the formats installed)

Required scope

FileDocument.Formats requires QuickLook.StageRoot.

Props

3 documented props

FileDocument.Formats props
Prop	Type	Default
`formats`	`readonly DocumentFormat[]`	`[]`
`except`	`boolean`	`false`
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-document/formats.tsx

FileDocument.Contentgate

Loading while the bytes are on their way, Failed when the read was refused or exceeded its bound, and Content with { bytes, name } once they have arrived.

Capability: previews

Required scope

FileDocument.Content requires FileDocument.Root.

FileDocument.Content requires QuickLook.StageRoot.

Props

1 documented props

FileDocument.Content props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { bytes: ArrayBuffer; name: string }) => ReactNode)`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-document/content.tsx

DocumentDocxcontent · Generic · <div>

DocumentDocx takes bytes (an ArrayBuffer), loading and failed (ReactNodes it shows while parsing and when the file cannot be drawn). It stays read-only: nothing is written back.

Props

2 documented props · Native <div> attributes supported

DocumentDocx props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Also inherits DocxDocumentProps. See TypeScript for the complete declaration.

Source: @slices.sh/file-storage/src/headless/document-docx/index.tsx

DocumentPdfcontent · <div>

DocumentPdf takes bytes (an ArrayBuffer), loading and failed (ReactNodes it shows while parsing and when the file cannot be drawn). It stays read-only: nothing is written back.

Capability: assets (the versioned viewer files)

Props

2 documented props · Native <div> attributes supported

DocumentPdf props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Also inherits Omit<PdfDocumentProps, "wasmUrl">. See TypeScript for the complete declaration.

Source: @slices.sh/file-storage/src/headless/document-pdf/index.tsx

DocumentPptxcontent · <div>

DocumentPptx takes bytes (an ArrayBuffer), loading and failed (ReactNodes it shows while parsing and when the file cannot be drawn). It stays read-only: nothing is written back.

Capability: assets (the versioned viewer files)

Props

2 documented props · Native <div> attributes supported

DocumentPptx props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Also inherits Omit<PptxDocumentProps, "wasmUrl" | "workerUrl">. See TypeScript for the complete declaration.

Source: @slices.sh/file-storage/src/headless/document-pptx/index.tsx

DocumentXlsxcontent · Generic · <div>

DocumentXlsx takes bytes (an ArrayBuffer), name (the file name, used for sheet titles), loading and failed (ReactNodes it shows while parsing and when the file cannot be drawn). It stays read-only: nothing is written back.

Props

2 documented props · Native <div> attributes supported

DocumentXlsx props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Also inherits XlsxDocumentProps. See TypeScript for the complete declaration.

Source: @slices.sh/file-storage/src/headless/document-xlsx/index.tsx

FileDocument.Loadinggate

Loading while the bytes are on their way, Failed when the read was refused or exceeded its bound, and Content with { bytes, name } once they have arrived.

Capability: previews

Required scope

FileDocument.Loading requires FileDocument.Root.

Props

1 documented props

FileDocument.Loading props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-document/loading.tsx

FileDocument.Failedgate

Loading while the bytes are on their way, Failed when the read was refused or exceeded its bound, and Content with { bytes, name } once they have arrived.

Capability: previews

Required scope

FileDocument.Failed requires FileDocument.Root.

Props

1 documented props

FileDocument.Failed props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-document/failed.tsx

FileDocument.Boundarycontent

A failed lazy chunk or parser does not take down the surrounding file browser.

Props

3 documented props

FileDocument.Boundary props
Prop	Type	Default
`fallback`Required	`ReactNode`	`—`
`resetKey`	`unknown`	`—`
`children`	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/file-document/boundary.tsx

Files.Containerscope

The one place a file explorer talks to the file service. It maps the client onto what the screen below draws: the folder that is open and its pages (`Files.Root`), the folders read besides it, from the store's listings or from `loadChildren`, and the address of every file and every picture, which the parts ask the client for and the server signs. What the screen may do is read here too, from what the client has: a part that needs `upload` asks `Files.CanUpload`, so a service with none gets a browser with no upload button and no drop, and not a button that fails when pressed. The screen never calls the service itself: pattern code calls no hook, and every part under here reaches the service through this container's contexts. → docs/rules/patterns-read-no-state.md

Props

2 documented props

Files.Container props
Prop	Type	Default
`loadChildren` Where a folder's children come from when it is not the store's own listing.	`LoadChildren`	`—`
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Also inherits Omit<FilesRootProps, "children">. See TypeScript for the complete declaration.

Source: @slices.sh/file-storage/src/headless/container.tsx

Files.Entriesscope

What the browser is showing: the directory's children, or what the search found. Under a folder that is open, in a tree, its entries follow it with how far in they are. One part for both, because a screen that drew them separately would be two lists whose rows, selection and actions drifted apart — and a search that showed a different kind of row than the folder it searched is the thing people report as a bug. Where the screen draws uploads in place, each one that is on its way is a row among these, in the order of the rest, with `Files.Pending` to say how far it has got. A row that is not there yet cannot be opened, picked, renamed or moved: its parts say so themselves.

Props

1 documented props

Files.Entries props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/entries.tsx

Files.Entrycontent · <li>

The gate around everything a listed folder draws, the repeater of rows on screen, the row, the next page, roving keys over the rows, a windowed list for long folders and the live announcement of what the folder now holds.

Required scope

Files.Entry must be inside <Files.Entries>.

Files.Entry must be inside <Files.Root>.

Props

2 documented props · Native <li> attributes supported

Files.Entry props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: EntryState) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/entry.tsx

Upload.Rootscope

The queue, its limits, and its field registration when it has a name inside a Composer.

Props

12 documented props

Upload.Root props
Prop	Type	Default
`name` The key of this value in a Composer's message. With a name, inside a Composer, the uploader is a field: its value is the finished files, and it holds the submit while one uploads. Without one, or outside a Composer, it is a plain uploader.	`string`	`—`
`enabled` Left out or `true`: required, and a missing service throws. `"optional"`: renders its children and every upload part does nothing, which is what a pattern's paperclip passes. `false`: off. A Composer whose sink takes no files turns it off too.	`Enabled`	`—`
`config` The file-storage config, `"default"` when left out.	`string`	`—`
`bucket`	`string`	`—`
`path` The directory files land in.	`string`	`"/"`
`maxSize` Bytes. A larger file is turned away before anything is sent. The server's own limit, in `services/file-storage/limits.ts`, applies too: the lower of the two is the one enforced.	`number`	`—`
`maxFiles`	`number`	`—`
`accept` An `accept` attribute: `"image/*,.pdf"`. Offered to the picker and checked on the way in.	`string`	`—`
`multipart` Files from 5 MiB go up in resumable parts wherever the backend has them, so a large file survives a dropped connection and can be paused. On unless turned off: a screen that had to opt in sent a 2 GB file as one request. A backend without parts is sent whole.	`boolean`	`true`
`includeHidden` Hidden files inside a folder (`.DS_Store`, `.git/…`, `Thumbs.db`) are left out of what a folder drop or folder pick brings in. Say `includeHidden` to send them. A hidden file chosen on its own is always taken.	`boolean`	`false`
`ifExists` What a name that is taken does: replace, keep both, refuse, or `"ask"` and wait to be told. Left out, replace.	`IfExists \| "ask"`	`—`
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/upload-root.tsx

Upload.Uploadsscope

Every upload in the queue, each in its own scope.

Required scope

File.Uploads must be inside <File.Upload>.

Props

1 documented props

Upload.Uploads props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/uploads.tsx

Upload.Rowcontent · <li>

One upload's row. `data-state` is where it is, which is what a skin colours by, and `data-kind` what it is, which is what a skin draws an icon for.

Required scope

File.UploadRow must be inside <File.Uploads>.

Props

2 documented props · Native <li> attributes supported

Upload.Row props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { state: UploadState }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Source: @slices.sh/file-storage/src/headless/upload-row.tsx

When something is missing

No service configuration: Install the quick-look setup below and import "@/services". Required service roots report missing setup; gates do not replace that configuration.
Missing capability or parent scope: Follow each part’s context requirements and the example composition. Capability-aware controls hide when the provider cannot perform their action.

Read the setup guide →