From 2b9c2f358de52d1f9375730a083dc606ad6e14f2 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 1 Jul 2026 15:50:10 -0400
Subject: [PATCH 1/2] feat(headless): add FileUpload compound primitive

Adds a headless, unstyled FileUpload primitive (Root, Trigger, Dropzone, Item, ItemPreview, ItemDelete + useFileUpload hook) supporting file-picker and drag-and-drop selection, single/multiple modes, accept and maxSize filtering with an onReject callback, and image previews. Includes a swingset docs page.
---
 .changeset/headless-file-upload.md            |   2 +
 packages/headless/README.md                   |   1 +
 packages/headless/package.json                |   4 +
 .../src/primitives/file-upload/README.md      | 163 ++++++++
 .../src/primitives/file-upload/accept.ts      |  40 ++
 .../file-upload/file-upload-context.ts        |  60 +++
 .../file-upload/file-upload-dropzone.tsx      |  74 ++++
 .../file-upload/file-upload-item-delete.tsx   |  35 ++
 .../file-upload/file-upload-item-preview.tsx  |  51 +++
 .../file-upload/file-upload-item.tsx          |  40 ++
 .../file-upload/file-upload-root.tsx          | 174 ++++++++
 .../file-upload/file-upload-trigger.tsx       |  30 ++
 .../file-upload/file-upload.test.tsx          | 371 ++++++++++++++++++
 .../src/primitives/file-upload/index.ts       |  12 +
 .../src/primitives/file-upload/parts.ts       |  12 +
 packages/headless/vite.config.ts              |   1 +
 .../swingset/src/components/DocsViewer.tsx    |   1 +
 packages/swingset/src/lib/registry.ts         |   3 +
 packages/swingset/src/stories/file-upload.mdx | 159 ++++++++
 .../src/stories/file-upload.stories.tsx       |  54 +++
 20 files changed, 1287 insertions(+)
 create mode 100644 .changeset/headless-file-upload.md
 create mode 100644 packages/headless/src/primitives/file-upload/README.md
 create mode 100644 packages/headless/src/primitives/file-upload/accept.ts
 create mode 100644 packages/headless/src/primitives/file-upload/file-upload-context.ts
 create mode 100644 packages/headless/src/primitives/file-upload/file-upload-dropzone.tsx
 create mode 100644 packages/headless/src/primitives/file-upload/file-upload-item-delete.tsx
 create mode 100644 packages/headless/src/primitives/file-upload/file-upload-item-preview.tsx
 create mode 100644 packages/headless/src/primitives/file-upload/file-upload-item.tsx
 create mode 100644 packages/headless/src/primitives/file-upload/file-upload-root.tsx
 create mode 100644 packages/headless/src/primitives/file-upload/file-upload-trigger.tsx
 create mode 100644 packages/headless/src/primitives/file-upload/file-upload.test.tsx
 create mode 100644 packages/headless/src/primitives/file-upload/index.ts
 create mode 100644 packages/headless/src/primitives/file-upload/parts.ts
 create mode 100644 packages/swingset/src/stories/file-upload.mdx
 create mode 100644 packages/swingset/src/stories/file-upload.stories.tsx

diff --git a/.changeset/headless-file-upload.md b/.changeset/headless-file-upload.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/headless-file-upload.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/headless/README.md b/packages/headless/README.md
index f880871432d..09b25b6bf7d 100644
--- a/packages/headless/README.md
+++ b/packages/headless/README.md
@@ -11,6 +11,7 @@ This package is **internal** (`private: true`) and consumed by `@clerk/ui`. It e
 | Accordion    | `@clerk/headless/accordion`    | Expandable content sections with single/multiple mode         |
 | Autocomplete | `@clerk/headless/autocomplete` | Combobox input with filterable option list                    |
 | Dialog       | `@clerk/headless/dialog`       | Modal dialog with focus trapping and scroll lock              |
+| FileUpload   | `@clerk/headless/file-upload`  | File picker + drag-and-drop upload with image previews        |
 | Menu         | `@clerk/headless/menu`         | Dropdown and nested context menus with safe hover zones       |
 | Popover      | `@clerk/headless/popover`      | Non-modal floating content triggered by click                 |
 | Select       | `@clerk/headless/select`       | Dropdown select with typeahead and keyboard navigation        |
diff --git a/packages/headless/package.json b/packages/headless/package.json
index 495046e13a7..7a4bb60fffb 100644
--- a/packages/headless/package.json
+++ b/packages/headless/package.json
@@ -41,6 +41,10 @@
       "import": "./dist/primitives/dialog/index.js",
       "types": "./dist/primitives/dialog/index.d.ts"
     },
+    "./file-upload": {
+      "import": "./dist/primitives/file-upload/index.js",
+      "types": "./dist/primitives/file-upload/index.d.ts"
+    },
     "./hooks": {
       "import": "./dist/hooks/index.js",
       "types": "./dist/hooks/index.d.ts"
diff --git a/packages/headless/src/primitives/file-upload/README.md b/packages/headless/src/primitives/file-upload/README.md
new file mode 100644
index 00000000000..40a166771e2
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/README.md
@@ -0,0 +1,163 @@
+# FileUpload
+
+A headless file upload primitive. Users can pick files through a `Trigger` button or by dragging
+them onto a `Dropzone`, and selected files render as compound `Item` parts with an optional image
+`Preview`. Supports controlled/uncontrolled selection, `accept` filtering (applied to both the
+picker and dropped files), single/multiple modes, and a disabled state.
+
+## When to Use
+
+- Any file input where you want the native picker behind your own styled trigger.
+- Drag-and-drop upload zones with live image thumbnails.
+- Avatar / logo pickers (single mode) or multi-file attachment lists (multiple mode).
+
+The primitive owns a hidden `<input type="file">` internally, so you never render one yourself. It
+emits zero styles — everything is driven by `data-cl-*` attributes.
+
+## Usage
+
+```tsx
+import { FileUpload } from '@clerk/headless/file-upload';
+
+function Uploader() {
+  return (
+    <FileUpload.Root
+      accept='image/*'
+      multiple
+    >
+      <FileUpload.Dropzone>
+        <FileUpload.Trigger>Choose files</FileUpload.Trigger>
+        <p>or drag files here</p>
+      </FileUpload.Dropzone>
+
+      <FileList />
+    </FileUpload.Root>
+  );
+}
+
+// Read the live file list and render each file as an Item.
+function FileList() {
+  const { files } = FileUpload.useFileUpload();
+  return (
+    <ul>
+      {files.map(file => (
+        <li key={file.name}>
+          <FileUpload.Item file={file}>
+            <FileUpload.ItemPreview />
+            <span>{file.name}</span>
+            <FileUpload.ItemDelete>Remove</FileUpload.ItemDelete>
+          </FileUpload.Item>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+`ItemPreview` renders an `<img>` only for image files; for other types it renders nothing, so it is
+safe to include unconditionally.
+
+### Controlled
+
+```tsx
+const [files, setFiles] = useState<File[]>([]);
+
+<FileUpload.Root
+  value={files}
+  onValueChange={setFiles}
+>
+  {/* ... */}
+</FileUpload.Root>;
+```
+
+### Single file (avatar)
+
+```tsx
+<FileUpload.Root accept='image/*'>
+  <FileUpload.Trigger>Upload avatar</FileUpload.Trigger>
+</FileUpload.Root>
+```
+
+In single mode a new selection replaces the previous file; in multiple mode selections are appended.
+
+### Validation
+
+`accept` and `maxSize` reject non-matching files, and `onReject` reports them so you can show an
+error. Rejections fire for both the picker and drops; accepted files in the same batch are still
+added.
+
+```tsx
+<FileUpload.Root
+  accept='image/png,image/jpeg'
+  maxSize={10 * 1000 * 1000}
+  onReject={rejections => {
+    for (const { file, reason } of rejections) {
+      setError(reason === 'size' ? `${file.name} is too large` : `${file.name} is not a supported type`);
+    }
+  }}
+  onValueChange={([file]) => file && upload(file)}
+>
+  <FileUpload.Trigger>Upload</FileUpload.Trigger>
+</FileUpload.Root>
+```
+
+## Parts
+
+| Part                     | Default Element | Description                                                         |
+| ------------------------ | --------------- | ------------------------------------------------------------------- |
+| `FileUpload.Root`        | `<div>`         | Owns the file state + hidden input, provides context                |
+| `FileUpload.Trigger`     | `<button>`      | Opens the native file picker                                        |
+| `FileUpload.Dropzone`    | `<div>`         | Drag-and-drop target; filters dropped files by `accept`             |
+| `FileUpload.Item`        | `<div>`         | Wraps a single selected file, provides item context                 |
+| `FileUpload.ItemPreview` | `<img>`         | Image thumbnail for the item's file (renders nothing for non-image) |
+| `FileUpload.ItemDelete`  | `<button>`      | Removes the item's file                                             |
+
+`FileUpload.useFileUpload()` is a hook (not a component) that returns
+`{ files, addFiles, removeFile, clearFiles, openFilePicker, disabled }` for reading the selection
+and driving custom UI. It must be called inside `FileUpload.Root`.
+
+## Props
+
+### `FileUpload.Root`
+
+| Prop            | Type                                    | Default | Description                                                    |
+| --------------- | --------------------------------------- | ------- | -------------------------------------------------------------- |
+| `value`         | `File[]`                                | —       | Controlled list of selected files                              |
+| `defaultValue`  | `File[]`                                | `[]`    | Initial list of files (uncontrolled)                           |
+| `onValueChange` | `(files: File[]) => void`               | —       | Called with the full list whenever it changes                  |
+| `multiple`      | `boolean`                               | `false` | Allow selecting more than one file                             |
+| `accept`        | `string`                                | —       | `accept` string (e.g. `image/*,.pdf`), also filters drops      |
+| `maxSize`       | `number`                                | —       | Max size in bytes for a single file; larger files are rejected |
+| `onReject`      | `(rejections: FileRejection[]) => void` | —       | Called with files rejected by `accept` or `maxSize`            |
+| `disabled`      | `boolean`                               | `false` | Disables the trigger, dropzone, and picker                     |
+
+A `FileRejection` is `{ file: File; reason: 'accept' | 'size' }`. Rejections are reported for both
+the picker and drops; `accept` is checked before `maxSize`. Accepted files in the same batch are
+still added.
+
+### `FileUpload.Item`
+
+| Prop   | Type   | Default | Description                   |
+| ------ | ------ | ------- | ----------------------------- |
+| `file` | `File` | —       | The file this item represents |
+
+Other parts take no additional props. All parts accept a `render` prop for polymorphic rendering and
+standard HTML attributes for their default element.
+
+## Data Attributes
+
+| Attribute          | Applies To                          | Description                                     |
+| ------------------ | ----------------------------------- | ----------------------------------------------- |
+| `data-cl-slot`     | All parts                           | Part identifier (e.g. `"file-upload-dropzone"`) |
+| `data-cl-empty`    | Root                                | Present when no files are selected              |
+| `data-cl-dragging` | Dropzone                            | Present while a valid drag is over the zone     |
+| `data-cl-image`    | Item                                | Present when the item's file is an image        |
+| `data-cl-disabled` | Root, Trigger, Dropzone, ItemDelete | Present when disabled                           |
+
+## ARIA
+
+- The hidden `<input type="file">` is `aria-hidden` and removed from the tab order; the `Trigger`
+  button is the accessible control and forwards its click to the input.
+- `Trigger` and `ItemDelete` render real `<button type="button">` elements and reflect `disabled`.
+- `Dropzone` sets `aria-disabled` when the upload is disabled.
+- `ItemPreview` uses the file name as its `alt` text.
diff --git a/packages/headless/src/primitives/file-upload/accept.ts b/packages/headless/src/primitives/file-upload/accept.ts
new file mode 100644
index 00000000000..1d8995db8db
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/accept.ts
@@ -0,0 +1,40 @@
+/**
+ * Matches a file against an `accept` string using the same grammar as the
+ * native `<input type="file" accept>` attribute: a comma-separated list of
+ * file extensions (`.png`), exact MIME types (`image/png`), and wildcard MIME
+ * groups (`image/*`). A missing or empty `accept` accepts everything.
+ *
+ * The native file picker already enforces `accept`, but drag-and-drop bypasses
+ * it, so the Dropzone re-validates dropped files with this helper.
+ */
+export function isFileAccepted(file: File, accept: string | undefined): boolean {
+  if (!accept) {
+    return true;
+  }
+
+  const tokens = accept
+    .split(',')
+    .map(token => token.trim().toLowerCase())
+    .filter(Boolean);
+
+  if (tokens.length === 0) {
+    return true;
+  }
+
+  const fileType = file.type.toLowerCase();
+  const fileName = file.name.toLowerCase();
+
+  return tokens.some(token => {
+    if (token === '*' || token === '*/*') {
+      return true;
+    }
+    if (token.startsWith('.')) {
+      return fileName.endsWith(token);
+    }
+    if (token.endsWith('/*')) {
+      // Wildcard MIME group, e.g. `image/*` matches `image/png`.
+      return fileType.startsWith(`${token.slice(0, -1)}`);
+    }
+    return fileType === token;
+  });
+}
diff --git a/packages/headless/src/primitives/file-upload/file-upload-context.ts b/packages/headless/src/primitives/file-upload/file-upload-context.ts
new file mode 100644
index 00000000000..d47c564297b
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/file-upload-context.ts
@@ -0,0 +1,60 @@
+import { createContext, useContext } from 'react';
+
+export interface FileUploadContextValue {
+  /** The currently selected files. */
+  files: File[];
+  /** Whether the whole upload is disabled. */
+  disabled: boolean;
+  /** Whether more than one file can be selected. */
+  multiple: boolean;
+  /** The `accept` string forwarded to the hidden input and used to filter drops. */
+  accept: string | undefined;
+  /** Add files, applying `accept` filtering and single/multiple semantics. */
+  addFiles: (incoming: FileList | File[]) => void;
+  /** Remove a single file by identity. */
+  removeFile: (file: File) => void;
+  /** Remove every selected file. */
+  clearFiles: () => void;
+  /** Open the native file picker (clicks the hidden input). */
+  openFilePicker: () => void;
+}
+
+export const FileUploadContext = createContext<FileUploadContextValue | null>(null);
+
+export function useFileUploadContext(): FileUploadContextValue {
+  const ctx = useContext(FileUploadContext);
+  if (!ctx) {
+    throw new Error('FileUpload compound components must be used within <FileUpload.Root>');
+  }
+  return ctx;
+}
+
+export interface FileUploadItemContextValue {
+  /** The file this item represents. */
+  file: File;
+  /** Remove this file from the upload. */
+  remove: () => void;
+}
+
+export const FileUploadItemContext = createContext<FileUploadItemContextValue | null>(null);
+
+export function useFileUploadItemContext(): FileUploadItemContextValue {
+  const ctx = useContext(FileUploadItemContext);
+  if (!ctx) {
+    throw new Error('FileUpload item parts must be used within <FileUpload.Item>');
+  }
+  return ctx;
+}
+
+/**
+ * Reads the current upload state and actions. Use this to render your own list
+ * of files (wrapping each in `<FileUpload.Item>`), a file count, or a custom
+ * clear button. Must be called inside `<FileUpload.Root>`.
+ */
+export function useFileUpload(): Pick<
+  FileUploadContextValue,
+  'files' | 'addFiles' | 'removeFile' | 'clearFiles' | 'openFilePicker' | 'disabled'
+> {
+  const { files, addFiles, removeFile, clearFiles, openFilePicker, disabled } = useFileUploadContext();
+  return { files, addFiles, removeFile, clearFiles, openFilePicker, disabled };
+}
diff --git a/packages/headless/src/primitives/file-upload/file-upload-dropzone.tsx b/packages/headless/src/primitives/file-upload/file-upload-dropzone.tsx
new file mode 100644
index 00000000000..378ef383024
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/file-upload-dropzone.tsx
@@ -0,0 +1,74 @@
+'use client';
+
+import { type DragEvent, useRef, useState } from 'react';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useFileUploadContext } from './file-upload-context';
+
+export type FileUploadDropzoneProps = ComponentProps<'div'>;
+
+export function FileUploadDropzone(props: FileUploadDropzoneProps) {
+  const { render, ...otherProps } = props;
+  const { disabled, addFiles } = useFileUploadContext();
+
+  const [dragging, setDragging] = useState(false);
+  // Counts enter/leave events so dragging over child elements does not flicker
+  // the drag state (dragenter/dragleave fire per nested element).
+  const dragDepth = useRef(0);
+
+  const state = { dragging, disabled };
+
+  const defaultProps: Record<string, unknown> = {
+    'data-cl-slot': 'file-upload-dropzone',
+    'aria-disabled': disabled || undefined,
+    onDragEnter: (event: DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      if (disabled) {
+        return;
+      }
+      dragDepth.current += 1;
+      setDragging(true);
+    },
+    onDragOver: (event: DragEvent<HTMLDivElement>) => {
+      // Required for the element to be a valid drop target.
+      event.preventDefault();
+      if (!disabled) {
+        event.dataTransfer.dropEffect = 'copy';
+      }
+    },
+    onDragLeave: (event: DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      if (disabled) {
+        return;
+      }
+      dragDepth.current -= 1;
+      if (dragDepth.current <= 0) {
+        dragDepth.current = 0;
+        setDragging(false);
+      }
+    },
+    onDrop: (event: DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragDepth.current = 0;
+      setDragging(false);
+      if (disabled) {
+        return;
+      }
+      const { files } = event.dataTransfer;
+      if (files && files.length > 0) {
+        addFiles(files);
+      }
+    },
+  };
+
+  return renderElement({
+    defaultTagName: 'div',
+    render,
+    state,
+    stateAttributesMapping: {
+      dragging: (v: boolean) => (v ? { 'data-cl-dragging': '' } : null),
+      disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+    },
+    props: mergeProps<'div'>(defaultProps, otherProps),
+  });
+}
diff --git a/packages/headless/src/primitives/file-upload/file-upload-item-delete.tsx b/packages/headless/src/primitives/file-upload/file-upload-item-delete.tsx
new file mode 100644
index 00000000000..eb571e7bcd6
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/file-upload-item-delete.tsx
@@ -0,0 +1,35 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useFileUploadContext, useFileUploadItemContext } from './file-upload-context';
+
+export type FileUploadItemDeleteProps = ComponentProps<'button'>;
+
+export function FileUploadItemDelete(props: FileUploadItemDeleteProps) {
+  const { render, ...otherProps } = props;
+  const { disabled } = useFileUploadContext();
+  const { remove } = useFileUploadItemContext();
+
+  const state = { disabled };
+
+  const defaultProps: Record<string, unknown> = {
+    'data-cl-slot': 'file-upload-item-delete',
+    type: 'button' as const,
+    disabled,
+    onClick: () => {
+      if (!disabled) {
+        remove();
+      }
+    },
+  };
+
+  return renderElement({
+    defaultTagName: 'button',
+    render,
+    state,
+    stateAttributesMapping: {
+      disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+    },
+    props: mergeProps<'button'>(defaultProps, otherProps),
+  });
+}
diff --git a/packages/headless/src/primitives/file-upload/file-upload-item-preview.tsx b/packages/headless/src/primitives/file-upload/file-upload-item-preview.tsx
new file mode 100644
index 00000000000..b5b6f303542
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/file-upload-item-preview.tsx
@@ -0,0 +1,51 @@
+'use client';
+
+import React, { useEffect, useState } from 'react';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useFileUploadItemContext } from './file-upload-context';
+
+export type FileUploadItemPreviewProps = ComponentProps<'img'>;
+
+/**
+ * Renders an `<img>` thumbnail for the item's file when it is an image. For
+ * non-image files it renders nothing, so it is safe to drop in unconditionally.
+ * The object URL is created on mount and revoked on unmount to avoid leaks.
+ */
+export const FileUploadItemPreview = React.forwardRef<HTMLImageElement, FileUploadItemPreviewProps>(
+  function FileUploadItemPreview(props, ref) {
+    const { render, ...otherProps } = props;
+    const { file } = useFileUploadItemContext();
+
+    const isImage = file.type.startsWith('image/');
+    const [objectUrl, setObjectUrl] = useState<string | undefined>(undefined);
+
+    useEffect(() => {
+      if (!isImage) {
+        return;
+      }
+      const url = URL.createObjectURL(file);
+      setObjectUrl(url);
+      return () => {
+        URL.revokeObjectURL(url);
+        setObjectUrl(undefined);
+      };
+    }, [file, isImage]);
+
+    const defaultProps: Record<string, unknown> = {
+      'data-cl-slot': 'file-upload-item-preview',
+      src: objectUrl,
+      alt: file.name,
+      ref,
+    };
+
+    return renderElement({
+      defaultTagName: 'img',
+      render,
+      // Only render once we are an image with a ready object URL, so we never
+      // emit an <img> with an empty src.
+      enabled: isImage && objectUrl != null,
+      props: mergeProps<'img'>(defaultProps, otherProps),
+    });
+  },
+);
diff --git a/packages/headless/src/primitives/file-upload/file-upload-item.tsx b/packages/headless/src/primitives/file-upload/file-upload-item.tsx
new file mode 100644
index 00000000000..3a1123d5adc
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/file-upload-item.tsx
@@ -0,0 +1,40 @@
+'use client';
+
+import { useCallback, useMemo } from 'react';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { FileUploadItemContext, type FileUploadItemContextValue, useFileUploadContext } from './file-upload-context';
+
+export interface FileUploadItemProps extends ComponentProps<'div'> {
+  /** The file this item represents (typically from `useFileUpload().files`). */
+  file: File;
+}
+
+export function FileUploadItem(props: FileUploadItemProps) {
+  const { render, file, ...otherProps } = props;
+  const { removeFile } = useFileUploadContext();
+
+  const remove = useCallback(() => removeFile(file), [removeFile, file]);
+
+  const itemContextValue = useMemo<FileUploadItemContextValue>(() => ({ file, remove }), [file, remove]);
+
+  const state = { image: file.type.startsWith('image/') };
+
+  const defaultProps: Record<string, unknown> = {
+    'data-cl-slot': 'file-upload-item',
+  };
+
+  return (
+    <FileUploadItemContext.Provider value={itemContextValue}>
+      {renderElement({
+        defaultTagName: 'div',
+        render,
+        state,
+        stateAttributesMapping: {
+          image: (v: boolean) => (v ? { 'data-cl-image': '' } : null),
+        },
+        props: mergeProps<'div'>(defaultProps, otherProps),
+      })}
+    </FileUploadItemContext.Provider>
+  );
+}
diff --git a/packages/headless/src/primitives/file-upload/file-upload-root.tsx b/packages/headless/src/primitives/file-upload/file-upload-root.tsx
new file mode 100644
index 00000000000..4e45660d3e8
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/file-upload-root.tsx
@@ -0,0 +1,174 @@
+'use client';
+
+import { type CSSProperties, type ReactNode, useCallback, useId, useMemo, useRef } from 'react';
+
+import { useControllableState } from '../../hooks/use-controllable-state';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { isFileAccepted } from './accept';
+import { FileUploadContext, type FileUploadContextValue } from './file-upload-context';
+
+/** Why a file was rejected when added. */
+export type FileRejectionReason = 'accept' | 'size';
+
+export interface FileRejection {
+  /** The rejected file. */
+  file: File;
+  /** `'accept'` for a type/extension mismatch, `'size'` for exceeding `maxSize`. */
+  reason: FileRejectionReason;
+}
+
+export interface FileUploadProps extends Omit<ComponentProps<'div'>, 'value' | 'defaultValue'> {
+  /** Controlled list of selected files. */
+  value?: File[];
+  /** Initial list of selected files (uncontrolled). @default [] */
+  defaultValue?: File[];
+  /** Called with the full file list whenever the selection changes. */
+  onValueChange?: (files: File[]) => void;
+  /** Allow selecting more than one file. @default false */
+  multiple?: boolean;
+  /** `accept` string (e.g. `image/*,.pdf`) applied to the picker and dropped files. */
+  accept?: string;
+  /** Maximum size, in bytes, for a single file. Larger files are rejected. */
+  maxSize?: number;
+  /**
+   * Called with every file rejected by `accept` or `maxSize` when a selection is
+   * attempted (via the picker or a drop). Use it to surface validation feedback.
+   */
+  onReject?: (rejections: FileRejection[]) => void;
+  /** Disable the trigger, dropzone, and picker. @default false */
+  disabled?: boolean;
+  children: ReactNode;
+}
+
+// The hidden input stays interactive (a keyboard user reaches it through the
+// Trigger button, which forwards the click) but is removed from layout.
+const visuallyHiddenInputStyle: CSSProperties = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};
+
+export function FileUploadRoot(props: FileUploadProps) {
+  const {
+    render,
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    multiple = false,
+    accept,
+    maxSize,
+    onReject,
+    disabled = false,
+    children,
+    ...otherProps
+  } = props;
+
+  const [files, setFiles] = useControllableState(valueProp, defaultValue ?? [], onValueChange);
+
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const rootId = useId();
+  const inputId = `${rootId}input`;
+
+  const addFiles = useCallback(
+    (incoming: FileList | File[]) => {
+      const accepted: File[] = [];
+      const rejected: FileRejection[] = [];
+      for (const file of Array.from(incoming)) {
+        if (!isFileAccepted(file, accept)) {
+          rejected.push({ file, reason: 'accept' });
+        } else if (maxSize != null && file.size > maxSize) {
+          rejected.push({ file, reason: 'size' });
+        } else {
+          accepted.push(file);
+        }
+      }
+
+      if (rejected.length > 0) {
+        onReject?.(rejected);
+      }
+      if (accepted.length === 0) {
+        return;
+      }
+      // Single mode keeps only the first accepted file; multiple mode appends.
+      setFiles(multiple ? [...files, ...accepted] : [accepted[0]]);
+    },
+    [files, multiple, accept, maxSize, onReject, setFiles],
+  );
+
+  const removeFile = useCallback(
+    (file: File) => {
+      setFiles(files.filter(f => f !== file));
+    },
+    [files, setFiles],
+  );
+
+  const clearFiles = useCallback(() => {
+    setFiles([]);
+  }, [setFiles]);
+
+  const openFilePicker = useCallback(() => {
+    if (!disabled) {
+      inputRef.current?.click();
+    }
+  }, [disabled]);
+
+  const contextValue = useMemo<FileUploadContextValue>(
+    () => ({ files, disabled, multiple, accept, addFiles, removeFile, clearFiles, openFilePicker }),
+    [files, disabled, multiple, accept, addFiles, removeFile, clearFiles, openFilePicker],
+  );
+
+  const state = { disabled, empty: files.length === 0 };
+
+  const defaultProps: Record<string, unknown> = {
+    'data-cl-slot': 'file-upload-root',
+    children: (
+      <>
+        <input
+          ref={inputRef}
+          id={inputId}
+          type='file'
+          accept={accept}
+          multiple={multiple}
+          disabled={disabled}
+          // The Trigger button is the accessible control; it forwards clicks to
+          // this input, so the input itself is hidden from assistive tech and
+          // taken out of the tab order to avoid a redundant, unlabelled field.
+          aria-hidden='true'
+          tabIndex={-1}
+          data-cl-slot='file-upload-input'
+          style={visuallyHiddenInputStyle}
+          onChange={event => {
+            const list = event.currentTarget.files;
+            if (list && list.length > 0) {
+              addFiles(list);
+            }
+            // Reset so selecting the same file again still fires `change`.
+            event.currentTarget.value = '';
+          }}
+        />
+        {children}
+      </>
+    ),
+  };
+
+  return (
+    <FileUploadContext.Provider value={contextValue}>
+      {renderElement({
+        defaultTagName: 'div',
+        render,
+        state,
+        stateAttributesMapping: {
+          disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+          empty: (v: boolean) => (v ? { 'data-cl-empty': '' } : null),
+        },
+        props: mergeProps<'div'>(defaultProps, otherProps),
+      })}
+    </FileUploadContext.Provider>
+  );
+}
diff --git a/packages/headless/src/primitives/file-upload/file-upload-trigger.tsx b/packages/headless/src/primitives/file-upload/file-upload-trigger.tsx
new file mode 100644
index 00000000000..558e9454469
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/file-upload-trigger.tsx
@@ -0,0 +1,30 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useFileUploadContext } from './file-upload-context';
+
+export type FileUploadTriggerProps = ComponentProps<'button'>;
+
+export function FileUploadTrigger(props: FileUploadTriggerProps) {
+  const { render, ...otherProps } = props;
+  const { disabled, openFilePicker } = useFileUploadContext();
+
+  const state = { disabled };
+
+  const defaultProps: Record<string, unknown> = {
+    'data-cl-slot': 'file-upload-trigger',
+    type: 'button' as const,
+    disabled,
+    onClick: () => openFilePicker(),
+  };
+
+  return renderElement({
+    defaultTagName: 'button',
+    render,
+    state,
+    stateAttributesMapping: {
+      disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+    },
+    props: mergeProps<'button'>(defaultProps, otherProps),
+  });
+}
diff --git a/packages/headless/src/primitives/file-upload/file-upload.test.tsx b/packages/headless/src/primitives/file-upload/file-upload.test.tsx
new file mode 100644
index 00000000000..c6381cd0485
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/file-upload.test.tsx
@@ -0,0 +1,371 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { axe } from '../../test-utils/axe';
+import { FileUpload } from './index';
+
+afterEach(() => cleanup());
+
+function makeFile(name: string, type: string) {
+  return new File(['content'], name, { type });
+}
+
+/** A default composition exercising every part, driven by the live file list. */
+function Harness(props: Partial<React.ComponentProps<typeof FileUpload.Root>> = {}) {
+  return (
+    <FileUpload.Root {...props}>
+      <FileUpload.Dropzone>
+        <FileUpload.Trigger>Choose files</FileUpload.Trigger>
+        Drag files here
+      </FileUpload.Dropzone>
+      <Previews />
+    </FileUpload.Root>
+  );
+}
+
+function Previews() {
+  const { files } = FileUpload.useFileUpload();
+  return (
+    <ul>
+      {files.map(file => (
+        <li key={file.name}>
+          <FileUpload.Item file={file}>
+            <FileUpload.ItemPreview />
+            <span>{file.name}</span>
+            <FileUpload.ItemDelete>Remove {file.name}</FileUpload.ItemDelete>
+          </FileUpload.Item>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+describe('FileUpload', () => {
+  describe('slot attributes', () => {
+    it('renders root, dropzone, trigger, and hidden input slots', () => {
+      render(<Harness />);
+      expect(document.querySelector('[data-cl-slot="file-upload-root"]')).toBeInTheDocument();
+      expect(document.querySelector('[data-cl-slot="file-upload-dropzone"]')).toBeInTheDocument();
+      expect(document.querySelector('[data-cl-slot="file-upload-trigger"]')).toBeInTheDocument();
+      expect(document.querySelector('[data-cl-slot="file-upload-input"]')).toBeInTheDocument();
+    });
+
+    it('marks the root empty until a file is selected', () => {
+      render(<Harness defaultValue={[makeFile('a.png', 'image/png')]} />);
+      expect(document.querySelector('[data-cl-slot="file-upload-root"]')).not.toHaveAttribute('data-cl-empty');
+
+      cleanup();
+      render(<Harness />);
+      expect(document.querySelector('[data-cl-slot="file-upload-root"]')).toHaveAttribute('data-cl-empty', '');
+    });
+  });
+
+  describe('trigger', () => {
+    it('opens the native picker by clicking the hidden input', async () => {
+      const user = userEvent.setup();
+      render(<Harness />);
+      const input = document.querySelector('[data-cl-slot="file-upload-input"]') as HTMLInputElement;
+      const clickSpy = vi.spyOn(input, 'click');
+
+      await user.click(screen.getByRole('button', { name: 'Choose files' }));
+
+      expect(clickSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('adds files chosen through the input', () => {
+      const onValueChange = vi.fn();
+      render(<Harness onValueChange={onValueChange} />);
+      const input = document.querySelector('[data-cl-slot="file-upload-input"]') as HTMLInputElement;
+
+      fireEvent.change(input, { target: { files: [makeFile('photo.png', 'image/png')] } });
+
+      expect(onValueChange).toHaveBeenCalledTimes(1);
+      expect(onValueChange.mock.calls[0][0]).toHaveLength(1);
+      expect(screen.getByText('photo.png')).toBeInTheDocument();
+    });
+  });
+
+  describe('drag and drop', () => {
+    it('toggles data-cl-dragging across enter/leave', () => {
+      render(<Harness />);
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      fireEvent.dragEnter(dropzone, { dataTransfer: { files: [] } });
+      expect(dropzone).toHaveAttribute('data-cl-dragging', '');
+
+      fireEvent.dragLeave(dropzone, { dataTransfer: { files: [] } });
+      expect(dropzone).not.toHaveAttribute('data-cl-dragging');
+    });
+
+    it('adds dropped files and clears the dragging state', () => {
+      render(<Harness multiple />);
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      fireEvent.dragEnter(dropzone, { dataTransfer: { files: [makeFile('a.png', 'image/png')] } });
+      fireEvent.drop(dropzone, { dataTransfer: { files: [makeFile('a.png', 'image/png')] } });
+
+      expect(screen.getByText('a.png')).toBeInTheDocument();
+      expect(dropzone).not.toHaveAttribute('data-cl-dragging');
+    });
+
+    it('filters dropped files by accept', () => {
+      const onValueChange = vi.fn();
+      render(
+        <Harness
+          accept='image/*'
+          multiple
+          onValueChange={onValueChange}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      fireEvent.drop(dropzone, {
+        dataTransfer: { files: [makeFile('a.png', 'image/png'), makeFile('doc.pdf', 'application/pdf')] },
+      });
+
+      expect(onValueChange).toHaveBeenCalledTimes(1);
+      const accepted: File[] = onValueChange.mock.calls[0][0];
+      expect(accepted.map(f => f.name)).toEqual(['a.png']);
+    });
+  });
+
+  describe('validation (onReject / maxSize)', () => {
+    function makeSizedFile(name: string, type: string, bytes: number) {
+      return new File([new Uint8Array(bytes)], name, { type });
+    }
+
+    it('reports accept mismatches to onReject with reason "accept"', () => {
+      const onReject = vi.fn();
+      render(
+        <Harness
+          accept='image/*'
+          multiple
+          onReject={onReject}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      fireEvent.drop(dropzone, {
+        dataTransfer: { files: [makeFile('a.png', 'image/png'), makeFile('doc.pdf', 'application/pdf')] },
+      });
+
+      expect(onReject).toHaveBeenCalledTimes(1);
+      const rejections = onReject.mock.calls[0][0];
+      expect(rejections).toEqual([{ file: expect.objectContaining({ name: 'doc.pdf' }), reason: 'accept' }]);
+    });
+
+    it('rejects files larger than maxSize with reason "size" and keeps the rest', () => {
+      const onReject = vi.fn();
+      const onValueChange = vi.fn();
+      render(
+        <Harness
+          multiple
+          maxSize={100}
+          onReject={onReject}
+          onValueChange={onValueChange}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+      const small = makeSizedFile('small.png', 'image/png', 50);
+      const big = makeSizedFile('big.png', 'image/png', 500);
+
+      fireEvent.drop(dropzone, { dataTransfer: { files: [small, big] } });
+
+      expect(onReject).toHaveBeenCalledTimes(1);
+      expect(onReject.mock.calls[0][0]).toEqual([{ file: big, reason: 'size' }]);
+      // The under-limit file is still accepted.
+      expect(onValueChange.mock.calls[0][0].map((f: File) => f.name)).toEqual(['small.png']);
+      expect(screen.getByText('small.png')).toBeInTheDocument();
+      expect(screen.queryByText('big.png')).not.toBeInTheDocument();
+    });
+
+    it('does not call onReject when every file is valid', () => {
+      const onReject = vi.fn();
+      render(
+        <Harness
+          accept='image/*'
+          maxSize={1000}
+          onReject={onReject}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      fireEvent.drop(dropzone, { dataTransfer: { files: [makeSizedFile('ok.png', 'image/png', 100)] } });
+
+      expect(onReject).not.toHaveBeenCalled();
+    });
+
+    it('checks accept before size (type mismatch wins)', () => {
+      const onReject = vi.fn();
+      render(
+        <Harness
+          accept='image/*'
+          maxSize={100}
+          onReject={onReject}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+      // A PDF that is also oversized should be rejected for the type, not the size.
+      fireEvent.drop(dropzone, { dataTransfer: { files: [makeSizedFile('big.pdf', 'application/pdf', 500)] } });
+
+      expect(onReject.mock.calls[0][0]).toEqual([
+        { file: expect.objectContaining({ name: 'big.pdf' }), reason: 'accept' },
+      ]);
+    });
+  });
+
+  describe('single vs multiple', () => {
+    it('replaces the file in single mode', () => {
+      render(<Harness defaultValue={[makeFile('first.png', 'image/png')]} />);
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      fireEvent.drop(dropzone, { dataTransfer: { files: [makeFile('second.png', 'image/png')] } });
+
+      expect(screen.queryByText('first.png')).not.toBeInTheDocument();
+      expect(screen.getByText('second.png')).toBeInTheDocument();
+    });
+
+    it('appends files in multiple mode', () => {
+      render(
+        <Harness
+          multiple
+          defaultValue={[makeFile('first.png', 'image/png')]}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      fireEvent.drop(dropzone, { dataTransfer: { files: [makeFile('second.png', 'image/png')] } });
+
+      expect(screen.getByText('first.png')).toBeInTheDocument();
+      expect(screen.getByText('second.png')).toBeInTheDocument();
+    });
+  });
+
+  describe('items', () => {
+    it('renders an <img> preview for image files', () => {
+      render(<Harness defaultValue={[makeFile('a.png', 'image/png')]} />);
+      const img = document.querySelector('[data-cl-slot="file-upload-item-preview"]');
+      expect(img?.tagName).toBe('IMG');
+      expect(img).toHaveAttribute('alt', 'a.png');
+      expect(img?.getAttribute('src')).toBeTruthy();
+    });
+
+    it('renders no preview for non-image files', () => {
+      render(<Harness defaultValue={[makeFile('doc.pdf', 'application/pdf')]} />);
+      expect(document.querySelector('[data-cl-slot="file-upload-item-preview"]')).not.toBeInTheDocument();
+    });
+
+    it('removes a file via ItemDelete', async () => {
+      const user = userEvent.setup();
+      render(
+        <Harness
+          multiple
+          defaultValue={[makeFile('a.png', 'image/png'), makeFile('b.png', 'image/png')]}
+        />,
+      );
+
+      await user.click(screen.getByRole('button', { name: 'Remove a.png' }));
+
+      expect(screen.queryByText('a.png')).not.toBeInTheDocument();
+      expect(screen.getByText('b.png')).toBeInTheDocument();
+    });
+  });
+
+  describe('controlled value', () => {
+    it('renders the controlled files and does not mutate them internally', () => {
+      const onValueChange = vi.fn();
+      render(
+        <Harness
+          value={[makeFile('locked.png', 'image/png')]}
+          onValueChange={onValueChange}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      expect(screen.getByText('locked.png')).toBeInTheDocument();
+
+      fireEvent.drop(dropzone, { dataTransfer: { files: [makeFile('new.png', 'image/png')] } });
+
+      // Controlled: the callback fires but the rendered list stays as provided.
+      expect(onValueChange).toHaveBeenCalledTimes(1);
+      expect(screen.queryByText('new.png')).not.toBeInTheDocument();
+      expect(screen.getByText('locked.png')).toBeInTheDocument();
+    });
+  });
+
+  describe('disabled', () => {
+    it('disables trigger and hidden input', () => {
+      render(<Harness disabled />);
+      expect(screen.getByRole('button', { name: 'Choose files' })).toBeDisabled();
+      expect(document.querySelector('[data-cl-slot="file-upload-input"]')).toBeDisabled();
+    });
+
+    it('ignores drops when disabled', () => {
+      const onValueChange = vi.fn();
+      render(
+        <Harness
+          disabled
+          onValueChange={onValueChange}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+
+      fireEvent.dragEnter(dropzone, { dataTransfer: { files: [makeFile('a.png', 'image/png')] } });
+      fireEvent.drop(dropzone, { dataTransfer: { files: [makeFile('a.png', 'image/png')] } });
+
+      expect(onValueChange).not.toHaveBeenCalled();
+      expect(dropzone).not.toHaveAttribute('data-cl-dragging');
+    });
+
+    it('applies data-cl-disabled on root, dropzone, and trigger', () => {
+      render(<Harness disabled />);
+      expect(document.querySelector('[data-cl-slot="file-upload-root"]')).toHaveAttribute('data-cl-disabled', '');
+      expect(document.querySelector('[data-cl-slot="file-upload-dropzone"]')).toHaveAttribute('data-cl-disabled', '');
+      expect(document.querySelector('[data-cl-slot="file-upload-trigger"]')).toHaveAttribute('data-cl-disabled', '');
+    });
+  });
+
+  describe('render prop', () => {
+    it('lets the trigger customize its element via render', () => {
+      render(
+        <FileUpload.Root>
+          <FileUpload.Trigger
+            render={props => (
+              // eslint-disable-next-line react/button-has-type -- `type` comes from the spread props; the Trigger sets type="button".
+              <button
+                {...props}
+                data-custom='yes'
+              />
+            )}
+          >
+            Upload
+          </FileUpload.Trigger>
+        </FileUpload.Root>,
+      );
+      const trigger = screen.getByRole('button', { name: 'Upload' });
+      expect(trigger).toHaveAttribute('data-custom', 'yes');
+      expect(trigger).toHaveAttribute('data-cl-slot', 'file-upload-trigger');
+    });
+  });
+
+  describe('context guards', () => {
+    it('throws when a part is used outside Root', () => {
+      const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      expect(() => render(<FileUpload.Trigger>x</FileUpload.Trigger>)).toThrow(/must be used within <FileUpload.Root>/);
+      spy.mockRestore();
+    });
+  });
+
+  describe('accessibility (axe)', () => {
+    it('has no violations when empty', async () => {
+      const { container } = render(<Harness />);
+      expect(await axe(container)).toHaveNoViolations();
+    });
+
+    it('has no violations with an image preview', async () => {
+      const { container } = render(<Harness defaultValue={[makeFile('a.png', 'image/png')]} />);
+      expect(await axe(container)).toHaveNoViolations();
+    });
+  });
+});
diff --git a/packages/headless/src/primitives/file-upload/index.ts b/packages/headless/src/primitives/file-upload/index.ts
new file mode 100644
index 00000000000..28d6cd6e1b2
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/index.ts
@@ -0,0 +1,12 @@
+export * as FileUpload from './parts';
+
+export type {
+  FileRejection,
+  FileRejectionReason,
+  FileUploadDropzoneProps,
+  FileUploadItemDeleteProps,
+  FileUploadItemPreviewProps,
+  FileUploadItemProps,
+  FileUploadProps,
+  FileUploadTriggerProps,
+} from './parts';
diff --git a/packages/headless/src/primitives/file-upload/parts.ts b/packages/headless/src/primitives/file-upload/parts.ts
new file mode 100644
index 00000000000..cc9cf9e54a0
--- /dev/null
+++ b/packages/headless/src/primitives/file-upload/parts.ts
@@ -0,0 +1,12 @@
+export {
+  type FileRejection,
+  type FileRejectionReason,
+  type FileUploadProps,
+  FileUploadRoot as Root,
+} from './file-upload-root';
+export { type FileUploadTriggerProps, FileUploadTrigger as Trigger } from './file-upload-trigger';
+export { type FileUploadDropzoneProps, FileUploadDropzone as Dropzone } from './file-upload-dropzone';
+export { type FileUploadItemProps, FileUploadItem as Item } from './file-upload-item';
+export { type FileUploadItemPreviewProps, FileUploadItemPreview as ItemPreview } from './file-upload-item-preview';
+export { type FileUploadItemDeleteProps, FileUploadItemDelete as ItemDelete } from './file-upload-item-delete';
+export { useFileUpload } from './file-upload-context';
diff --git a/packages/headless/vite.config.ts b/packages/headless/vite.config.ts
index 153d0aa443b..ad9fded53ea 100644
--- a/packages/headless/vite.config.ts
+++ b/packages/headless/vite.config.ts
@@ -21,6 +21,7 @@ export default defineConfig({
         'primitives/autocomplete/index': 'src/primitives/autocomplete/index.ts',
         'primitives/collapsible/index': 'src/primitives/collapsible/index.ts',
         'primitives/dialog/index': 'src/primitives/dialog/index.ts',
+        'primitives/file-upload/index': 'src/primitives/file-upload/index.ts',
         'utils/index': 'src/utils/index.ts',
         'hooks/index': 'src/hooks/index.ts',
         'hooks/use-controllable-state': 'src/hooks/use-controllable-state.ts',
diff --git a/packages/swingset/src/components/DocsViewer.tsx b/packages/swingset/src/components/DocsViewer.tsx
index 66c8423ae2a..1c33abeab29 100644
--- a/packages/swingset/src/components/DocsViewer.tsx
+++ b/packages/swingset/src/components/DocsViewer.tsx
@@ -39,6 +39,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     autocomplete: dynamic(() => import('../stories/autocomplete.mdx')),
     collapsible: dynamic(() => import('../stories/collapsible.mdx')),
     dialog: dynamic(() => import('../stories/dialog.mdx')),
+    'file-upload': dynamic(() => import('../stories/file-upload.mdx')),
     menu: dynamic(() => import('../stories/menu.mdx')),
     popover: dynamic(() => import('../stories/popover.mdx')),
     select: dynamic(() => import('../stories/select.mdx')),
diff --git a/packages/swingset/src/lib/registry.ts b/packages/swingset/src/lib/registry.ts
index ff0ee8b6f6a..c262d0b69ac 100644
--- a/packages/swingset/src/lib/registry.ts
+++ b/packages/swingset/src/lib/registry.ts
@@ -15,6 +15,7 @@ import {
 import { Default as DestructiveDefault, meta as destructiveMeta } from '../stories/destructive.stories';
 import { Default as DialogDefault, meta as dialogComponentMeta } from '../stories/dialog.component.stories';
 import { meta as dialogMeta } from '../stories/dialog.stories';
+import { meta as fileUploadMeta } from '../stories/file-upload.stories';
 import {
   Default as HeadingDefault,
   Intents as HeadingIntents,
@@ -106,6 +107,7 @@ const accordionModule: StoryModule = { meta: accordionMeta };
 const autocompleteModule: StoryModule = { meta: autocompleteMeta };
 const collapsibleModule: StoryModule = { meta: collapsibleMeta };
 const dialogModule: StoryModule = { meta: dialogMeta };
+const fileUploadModule: StoryModule = { meta: fileUploadMeta };
 const menuModule: StoryModule = { meta: menuMeta };
 const popoverModule: StoryModule = { meta: popoverMeta };
 const selectModule: StoryModule = { meta: selectMeta };
@@ -138,6 +140,7 @@ export const registry: StoryModule[] = [
   autocompleteModule,
   collapsibleModule,
   dialogModule,
+  fileUploadModule,
   menuModule,
   popoverModule,
   selectModule,
diff --git a/packages/swingset/src/stories/file-upload.mdx b/packages/swingset/src/stories/file-upload.mdx
new file mode 100644
index 00000000000..ed1d9715312
--- /dev/null
+++ b/packages/swingset/src/stories/file-upload.mdx
@@ -0,0 +1,159 @@
+import * as FileUploadStories from './file-upload.stories';
+
+# FileUpload
+
+A file picker that accepts input from a trigger button or drag-and-drop, from `@clerk/headless`.
+It is a **headless** primitive: it owns the selected-file state, a hidden `<input type="file">`,
+`accept` filtering (applied to both the picker and dropped files), single/multiple modes, and image
+preview thumbnails, but ships **no styles** — you bring your own CSS by targeting the `data-cl-*`
+attributes each part emits.
+
+## Example
+
+The demo below is intentionally unstyled — it renders the raw primitive so you can see its behavior.
+Click the trigger to open the native picker, or drag image files onto the area; each selected file
+renders an `<img>` preview with a remove button. Non-image files render no preview.
+
+<Story
+  name='Default'
+  storyModule={FileUploadStories}
+/>
+
+## Usage
+
+```tsx
+import { FileUpload } from '@clerk/headless/file-upload';
+
+<FileUpload.Root
+  accept='image/*'
+  multiple
+>
+  <FileUpload.Dropzone>
+    <FileUpload.Trigger>Choose files</FileUpload.Trigger>
+    <span>or drag files here</span>
+  </FileUpload.Dropzone>
+
+  <FileList />
+</FileUpload.Root>;
+```
+
+The selected files live in `FileUpload.Root`. Read them with the `useFileUpload` hook and render each
+one inside a `FileUpload.Item` — `ItemPreview` renders an `<img>` for images and nothing otherwise,
+so it is safe to include unconditionally:
+
+```tsx
+function FileList() {
+  const { files } = FileUpload.useFileUpload();
+  return (
+    <ul>
+      {files.map(file => (
+        <li key={file.name}>
+          <FileUpload.Item file={file}>
+            <FileUpload.ItemPreview />
+            <span>{file.name}</span>
+            <FileUpload.ItemDelete>Remove</FileUpload.ItemDelete>
+          </FileUpload.Item>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Single file (avatar)
+
+Omit `multiple` and a new selection replaces the previous file instead of appending.
+
+```tsx
+<FileUpload.Root accept='image/*'>
+  <FileUpload.Trigger>Upload avatar</FileUpload.Trigger>
+</FileUpload.Root>
+```
+
+### Controlled
+
+```tsx
+const [files, setFiles] = useState<File[]>([]);
+
+<FileUpload.Root
+  value={files}
+  onValueChange={setFiles}
+>
+  {/* ... */}
+</FileUpload.Root>;
+```
+
+## Parts
+
+| Part                     | Default Element | Description                                                          |
+| ------------------------ | --------------- | -------------------------------------------------------------------- |
+| `FileUpload.Root`        | `<div>`         | Root wrapper; owns file state and renders the hidden `<input>`       |
+| `FileUpload.Trigger`     | `<button>`      | Opens the native file picker                                         |
+| `FileUpload.Dropzone`    | `<div>`         | Drag-and-drop target; filters dropped files by `accept`              |
+| `FileUpload.Item`        | `<div>`         | Wraps one selected file; provides item context (file, remove)        |
+| `FileUpload.ItemPreview` | `<img>`         | Image thumbnail for the item's file (renders nothing for non-images) |
+| `FileUpload.ItemDelete`  | `<button>`      | Removes the item's file                                              |
+
+All parts accept a `render` prop for polymorphic rendering and standard HTML attributes for their
+default element. Compound parts throw if used outside their parent (`FileUpload.*` outside `Root`;
+`Item`-scoped parts outside `Item`).
+
+`FileUpload.useFileUpload()` is a hook (not a component) that returns
+`{ files, addFiles, removeFile, clearFiles, openFilePicker, disabled }` for reading the selection and
+driving custom UI. It must be called inside `FileUpload.Root`.
+
+## Props
+
+### `FileUpload.Root`
+
+| Prop                       | Type                                               | Default            | Description                                                |
+| -------------------------- | -------------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| <code>value</code>         | <code>File[]</code>                                | —                  | Controlled list of selected files                          |
+| <code>defaultValue</code>  | <code>File[]</code>                                | <code>[]</code>    | Initially selected files (uncontrolled)                    |
+| <code>onValueChange</code> | <code>(files: File[]) => void</code>               | —                  | Called with the full list whenever the selection changes   |
+| <code>multiple</code>      | <code>boolean</code>                               | <code>false</code> | Allow selecting more than one file                         |
+| <code>accept</code>        | <code>string</code>                                | —                  | `accept` filter (e.g. `image/*,.pdf`) for picker and drops |
+| <code>maxSize</code>       | <code>number</code>                                | —                  | Max size in bytes for a single file; larger files rejected |
+| <code>onReject</code>      | <code>(rejections: FileRejection[]) => void</code> | —                  | Called with files rejected by `accept` or `maxSize`        |
+| <code>disabled</code>      | <code>boolean</code>                               | <code>false</code> | Disable the trigger, dropzone, and picker                  |
+
+A `FileRejection` is `{ file: File; reason: 'accept' | 'size' }`. `onReject` fires for both the
+picker and drops, `accept` is checked before `maxSize`, and accepted files in the same batch are
+still added.
+
+### `FileUpload.Item`
+
+| Prop              | Type              | Default      | Description                   |
+| ----------------- | ----------------- | ------------ | ----------------------------- |
+| <code>file</code> | <code>File</code> | — (required) | The file this item represents |
+
+`FileUpload.Trigger`, `FileUpload.Dropzone`, `FileUpload.ItemPreview`, and `FileUpload.ItemDelete`
+take no additional props beyond standard HTML attributes for their default element.
+
+## Styling
+
+Each part emits `data-cl-*` attributes you can target with any CSS solution:
+
+| Attribute          | Applies To                          | Description                                     |
+| ------------------ | ----------------------------------- | ----------------------------------------------- |
+| `data-cl-slot`     | All parts                           | Part identifier (e.g. `"file-upload-dropzone"`) |
+| `data-cl-empty`    | Root                                | Present when no files are selected              |
+| `data-cl-dragging` | Dropzone                            | Present while a valid drag is over the zone     |
+| `data-cl-image`    | Item                                | Present when the item's file is an image        |
+| `data-cl-disabled` | Root, Trigger, Dropzone, ItemDelete | Present when disabled                           |
+
+```css
+[data-cl-slot='file-upload-dropzone'] {
+  border: 2px dashed var(--color-border);
+  border-radius: 8px;
+  padding: 24px;
+}
+[data-cl-slot='file-upload-dropzone'][data-cl-dragging] {
+  border-color: var(--color-accent);
+  background: var(--color-accent-subtle);
+}
+```
+
+The hidden `<input type="file">` is `aria-hidden` and out of the tab order; the `Trigger` button is
+the accessible control and forwards its click to the input. `ItemPreview` uses the file name as its
+`alt` text.
diff --git a/packages/swingset/src/stories/file-upload.stories.tsx b/packages/swingset/src/stories/file-upload.stories.tsx
new file mode 100644
index 00000000000..2e198612598
--- /dev/null
+++ b/packages/swingset/src/stories/file-upload.stories.tsx
@@ -0,0 +1,54 @@
+import { FileUpload } from '@clerk/headless/file-upload';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Headless primitives ship no styles. This single demo renders the primitive raw —
+// unstyled — so it faithfully reflects what `@clerk/headless` provides: file selection via
+// a trigger or drag-and-drop, live image previews, and the `data-cl-*` attributes each part
+// emits, with zero appearance. The only inline styles below constrain the preview thumbnail
+// so a full-resolution image can't blow out the demo; they are not part of the primitive.
+// It is embedded once into the overview via `<Story>` in the MDX (the one thing prose can't
+// convey: that picking or dropping a file actually renders a preview). There is no
+// interactive knob canvas for headless primitives.
+
+export const meta: StoryMeta = {
+  group: 'Primitives',
+  title: 'FileUpload',
+  label: 'File Upload',
+  source: 'packages/headless/src/primitives/file-upload/index.ts',
+};
+
+function SelectedFiles() {
+  const { files } = FileUpload.useFileUpload();
+  if (files.length === 0) {
+    return null;
+  }
+  return (
+    <ul>
+      {files.map(file => (
+        <li key={file.name}>
+          <FileUpload.Item file={file}>
+            <FileUpload.ItemPreview style={{ width: 48, height: 48, objectFit: 'cover' }} />
+            <span>{file.name}</span>
+            <FileUpload.ItemDelete>Remove</FileUpload.ItemDelete>
+          </FileUpload.Item>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export function Default() {
+  return (
+    <FileUpload.Root
+      accept='image/*'
+      multiple
+    >
+      <FileUpload.Dropzone>
+        <FileUpload.Trigger>Choose images</FileUpload.Trigger>
+        <span> or drag images here</span>
+      </FileUpload.Dropzone>
+      <SelectedFiles />
+    </FileUpload.Root>
+  );
+}

From 0fbd138f857a1514b349fa814baa8a18d9b5bd02 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 1 Jul 2026 16:02:57 -0400
Subject: [PATCH 2/2] fix(headless): report single-mode overflow files via
 onReject

In single-file mode, extra files from a multi-file drop were kept-first and silently discarded. Report them through onReject with a new 'overflow' rejection reason. Also key the swingset preview list by a composite file identity to avoid duplicate-filename collisions.
---
 .../src/primitives/file-upload/README.md      |  7 ++++---
 .../file-upload/file-upload-root.tsx          | 21 ++++++++++++++-----
 .../file-upload/file-upload.test.tsx          | 21 +++++++++++++++++++
 packages/swingset/src/stories/file-upload.mdx |  7 ++++---
 .../src/stories/file-upload.stories.tsx       |  2 +-
 5 files changed, 46 insertions(+), 12 deletions(-)

diff --git a/packages/headless/src/primitives/file-upload/README.md b/packages/headless/src/primitives/file-upload/README.md
index 40a166771e2..e53c81cd607 100644
--- a/packages/headless/src/primitives/file-upload/README.md
+++ b/packages/headless/src/primitives/file-upload/README.md
@@ -131,9 +131,10 @@ and driving custom UI. It must be called inside `FileUpload.Root`.
 | `onReject`      | `(rejections: FileRejection[]) => void` | —       | Called with files rejected by `accept` or `maxSize`            |
 | `disabled`      | `boolean`                               | `false` | Disables the trigger, dropzone, and picker                     |
 
-A `FileRejection` is `{ file: File; reason: 'accept' | 'size' }`. Rejections are reported for both
-the picker and drops; `accept` is checked before `maxSize`. Accepted files in the same batch are
-still added.
+A `FileRejection` is `{ file: File; reason: 'accept' | 'size' | 'overflow' }`. Rejections are
+reported for both the picker and drops; `accept` is checked before `maxSize`, and in single-file mode
+any files beyond the first are reported with reason `'overflow'` rather than dropped silently.
+Accepted files in the same batch are still added.
 
 ### `FileUpload.Item`
 
diff --git a/packages/headless/src/primitives/file-upload/file-upload-root.tsx b/packages/headless/src/primitives/file-upload/file-upload-root.tsx
index 4e45660d3e8..eb821e02e6b 100644
--- a/packages/headless/src/primitives/file-upload/file-upload-root.tsx
+++ b/packages/headless/src/primitives/file-upload/file-upload-root.tsx
@@ -8,12 +8,15 @@ import { isFileAccepted } from './accept';
 import { FileUploadContext, type FileUploadContextValue } from './file-upload-context';
 
 /** Why a file was rejected when added. */
-export type FileRejectionReason = 'accept' | 'size';
+export type FileRejectionReason = 'accept' | 'size' | 'overflow';
 
 export interface FileRejection {
   /** The rejected file. */
   file: File;
-  /** `'accept'` for a type/extension mismatch, `'size'` for exceeding `maxSize`. */
+  /**
+   * `'accept'` for a type/extension mismatch, `'size'` for exceeding `maxSize`,
+   * `'overflow'` for extra files supplied beyond the first in single-file mode.
+   */
   reason: FileRejectionReason;
 }
 
@@ -89,14 +92,22 @@ export function FileUploadRoot(props: FileUploadProps) {
         }
       }
 
+      // Single mode keeps only the first accepted file; the rest are reported as
+      // overflow rather than dropped silently.
+      const kept = multiple ? accepted : accepted.slice(0, 1);
+      if (!multiple) {
+        for (const file of accepted.slice(1)) {
+          rejected.push({ file, reason: 'overflow' });
+        }
+      }
+
       if (rejected.length > 0) {
         onReject?.(rejected);
       }
-      if (accepted.length === 0) {
+      if (kept.length === 0) {
         return;
       }
-      // Single mode keeps only the first accepted file; multiple mode appends.
-      setFiles(multiple ? [...files, ...accepted] : [accepted[0]]);
+      setFiles(multiple ? [...files, ...kept] : kept);
     },
     [files, multiple, accept, maxSize, onReject, setFiles],
   );
diff --git a/packages/headless/src/primitives/file-upload/file-upload.test.tsx b/packages/headless/src/primitives/file-upload/file-upload.test.tsx
index c6381cd0485..8ebd0a9d66c 100644
--- a/packages/headless/src/primitives/file-upload/file-upload.test.tsx
+++ b/packages/headless/src/primitives/file-upload/file-upload.test.tsx
@@ -196,6 +196,27 @@ describe('FileUpload', () => {
       expect(onReject).not.toHaveBeenCalled();
     });
 
+    it('reports extra files as "overflow" in single mode and keeps the first', () => {
+      const onReject = vi.fn();
+      const onValueChange = vi.fn();
+      // No `multiple` → single mode.
+      render(
+        <Harness
+          onReject={onReject}
+          onValueChange={onValueChange}
+        />,
+      );
+      const dropzone = document.querySelector('[data-cl-slot="file-upload-dropzone"]') as HTMLElement;
+      const first = makeFile('first.png', 'image/png');
+      const second = makeFile('second.png', 'image/png');
+
+      fireEvent.drop(dropzone, { dataTransfer: { files: [first, second] } });
+
+      expect(onValueChange.mock.calls[0][0].map((f: File) => f.name)).toEqual(['first.png']);
+      expect(onReject).toHaveBeenCalledTimes(1);
+      expect(onReject.mock.calls[0][0]).toEqual([{ file: second, reason: 'overflow' }]);
+    });
+
     it('checks accept before size (type mismatch wins)', () => {
       const onReject = vi.fn();
       render(
diff --git a/packages/swingset/src/stories/file-upload.mdx b/packages/swingset/src/stories/file-upload.mdx
index ed1d9715312..adb1ec101cf 100644
--- a/packages/swingset/src/stories/file-upload.mdx
+++ b/packages/swingset/src/stories/file-upload.mdx
@@ -117,9 +117,10 @@ driving custom UI. It must be called inside `FileUpload.Root`.
 | <code>onReject</code>      | <code>(rejections: FileRejection[]) => void</code> | —                  | Called with files rejected by `accept` or `maxSize`        |
 | <code>disabled</code>      | <code>boolean</code>                               | <code>false</code> | Disable the trigger, dropzone, and picker                  |
 
-A `FileRejection` is `{ file: File; reason: 'accept' | 'size' }`. `onReject` fires for both the
-picker and drops, `accept` is checked before `maxSize`, and accepted files in the same batch are
-still added.
+A `FileRejection` is `{ file: File; reason: 'accept' | 'size' | 'overflow' }`. `onReject` fires for
+both the picker and drops, `accept` is checked before `maxSize`, and in single-file mode any files
+beyond the first are reported as `'overflow'` rather than dropped silently. Accepted files in the
+same batch are still added.
 
 ### `FileUpload.Item`
 
diff --git a/packages/swingset/src/stories/file-upload.stories.tsx b/packages/swingset/src/stories/file-upload.stories.tsx
index 2e198612598..9c39865a4a3 100644
--- a/packages/swingset/src/stories/file-upload.stories.tsx
+++ b/packages/swingset/src/stories/file-upload.stories.tsx
@@ -26,7 +26,7 @@ function SelectedFiles() {
   return (
     <ul>
       {files.map(file => (
-        <li key={file.name}>
+        <li key={`${file.name}-${file.size}-${file.lastModified}`}>
           <FileUpload.Item file={file}>
             <FileUpload.ItemPreview style={{ width: 48, height: 48, objectFit: 'cover' }} />
             <span>{file.name}</span>