File Upload

File Upload supports native file selection, drag and drop, client-side validation, and optional automatic uploads. Without an onUpload handler, accepted files are listed as Ready to upload; the component does not send them anywhere.

ImportCopy Anchor Link

import { FileUpload, type FileUploadUploadHandler } from "@puzzle-ui/ui";

Basic usageCopy Anchor Link

Click the dropzone, press Enter or Space while it is focused, or drop a file onto it. Use title, description, and browseLabel to explain what to select.

Single-file mode is the default: a new accepted file replaces the previous selection and aborts its in-progress upload. A rejected file does not replace the current selection. Each listed file has a Remove button.

Multiple files and selection changesCopy Anchor Link

Set multiple to append accepted files across selections. onChange receives the entire accepted File[] whenever files are added, replaced, or removed, including [] after removing the last file.

The file list is managed internally; there are no controlled value or defaultValue props. Upload progress and completion do not call onChange.

Accepted types and limitsCopy Anchor Link

accept is an array of MIME types such as "application/pdf" or wildcards such as "image/*". File extensions such as ".png" are not supported by the component's validator. Files with an empty MIME type are rejected when an accept filter is configured.

maxFileSize limits each file, maxTotalSize limits the combined selected size, and maxFiles limits the count in multiple mode. Sizes are in bytes. Files are evaluated in selection order: valid files that fit are accepted, while rejected files are reported separately.

Rejections appear in an alert with the filename and reason. onReject receives the rejected files for that selection. New selections replace previous rejection messages; removing a selected file does not clear them.

<FileUpload
  accept={["image/png"]}
  onReject={(rejections) => {
    for (const { file, code, message } of rejections) {
      console.warn(file.name, code, message);
    }
  }}
/>

These are client-side checks for user feedback, not a security boundary. Validate file contents, types, sizes, and permissions again on your server.

Automatic uploads, progress, and retryCopy Anchor Link

Provide onUpload to start uploading each accepted file automatically. The handler receives the file and { signal, onProgress }. Report progress from 0 to 100; resolve the promise on success and reject it on failure. Error messages are displayed alongside a Retry button, which calls the handler again for that file.

The following local simulation intentionally fails each file's first attempt. Select a file to see progress and error feedback, then retry to complete it. No file data is sent anywhere.

Files upload independently. Progress is clamped to 0-100, and resolving the handler marks the file complete at 100. Removing a file, replacing it in single mode, or unmounting aborts its signal; pass that signal to your network client to cancel the actual request. Late results from aborted attempts are ignored.

Connect your upload endpointCopy Anchor Link

Use your application's endpoint and handle unsuccessful HTTP responses explicitly. fetch does not provide upload-progress events; omit intermediate progress or use a client that supports them.

const uploadFile: FileUploadUploadHandler = async (file, { signal }) => {
  const body = new FormData();
  body.append("file", file);

  const response = await fetch("/api/uploads", {
    method: "POST",
    body,
    signal,
  });

  if (!response.ok) {
    throw new Error("Upload failed (" + response.status + "). Please retry.");
  }
};

<FileUpload multiple onUpload={uploadFile} />;

Labels and validation stateCopy Anchor Link

Wrap the component in FormField for an external label, supporting text, and validation message. Its label targets the native file input. The supplied description and error relationships are preserved alongside File Upload's own description.

required sets the native file input's required attribute. It does not validate the internally managed file list: the native input is cleared after selection so the same file can be selected again. For form submission, validate the files received by onChange and send them explicitly using FormData or your upload handler. Do not rely on name and native form serialization to submit the displayed file list.

Disabled stateCopy Anchor Link

disabled prevents file selection, dropping, removal, and retry, and removes the dropzone from keyboard navigation. It does not cancel uploads that are already running.

APICopy Anchor Link

FileUploadCopy Anchor Link

Other supported div attributes are forwarded to the outer wrapper. children and a custom onDrop are not part of the API.

FileUploadUploadContextCopy Anchor Link

FileUploadUploadHandler is (file: File, context: FileUploadUploadContext) => Promise<void>.

FileUploadRejectionCopy Anchor Link

Exported item typesCopy Anchor Link

FileUploadItem describes the internal list entries. It is exported for typing, but callbacks receive files or rejections, not item records.

AccessibilityCopy Anchor Link

The dropzone is keyboard focusable and uses button semantics. Enter and Space open the native picker; disabled dropzones are skipped by Tab. Removal and retry controls have filename-specific accessible names.

The selected-file list announces additions and removals politely. Rejection messages use an alert, upload errors and completion use status messages, and progress bars have file-specific labels. Drag feedback is supplementary: users can always choose files with the keyboard instead.