File upload

• Type: Block

• Page: https://ui.xzero.co.uk/components/blocks/file-upload

• Markdown: https://ui.xzero.co.uk/components/blocks/file-upload/markdown

• Access: Free, open source

• Registry id: file-upload

• Source file: registry/components/file-upload/file-upload.tsx

• Built from: File picker, Progress, Feedback

• Keywords: react file upload, drag and drop upload, upload progress, file dropzone, multiple file upload, upload with retry

Use it for documents or media when people need to see upload progress and recover from invalid files.

When to use

• Uploading files with per-file progress, retry, and remove.
• Attachments that must be validated by type and size before upload.
• Uploads that should abort when a file is removed, via the AbortSignal.

When not to use

• Use file-dropzone when you only need to pick files without upload state.
• Use import-mapper when uploaded data needs column mapping.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/file-upload

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { FileUpload } from "@/components/xzero/file-upload/file-upload";

export function Attachments() {
  return (
    <FileUpload
      accept="image/*,.pdf"
      maxSize={10 * 1024 * 1024}
      onUpload={async (file, { onProgress, signal }) => {
        await uploadWithProgress(file, onProgress, signal);
      }}
    />
  );
}

API reference

FileUpload

A dropzone with a file list that validates type and size, runs your upload per file with progress, and supports retry and remove.

Prop	Type	Default	Description
accept	string	–	Comma-separated extensions or MIME types, including wildcards like image/*. Rejected files stay listed with an error.
maxSize	number	–	Maximum size in bytes. Larger files are listed with an error.
multiple	boolean	true	Allows several files. When false a new file replaces the old one.
disabled	boolean	false	Disables the dropzone and input.
label	string	"Upload files"	Dropzone heading.
description	string	"Drop files here or browse from your device."	Helper text, linked with aria-describedby.
value	FileUploadItem[]	–	Controlled file list.
onChange	(files: FileUploadItem[]) => void	–	Called when files are added or removed.
onUpload	(file: File, options: { onProgress: (percent: number) => void; signal: AbortSignal }) => Promise<void>	–	Uploads each valid file. Report 0-100 through onProgress, resolve when done, reject to mark it failed. Removing a file aborts its signal.

FileUploadItem

Item type: { id: string; file: File; error?: string }.

No props.

Keyboard interactions

Keys	Action
Enter / Space	Opens the file picker from the dropzone.
Tab	Moves through the dropzone and each row's retry and remove buttons.

Accessibility

• The dropzone is role=button with aria-disabled and aria-describedby for the helper text.
• An aria-live polite status line announces added, rejected, uploaded, failed, and removed files.
• Retry and remove buttons are labelled with the file name.
• After removing a file, focus moves to the neighbouring remove button or back to the dropzone.

Motion

• The dropzone label swaps to Drop to add files while dragging; rows open and close their height on a spring.
• One spring drives the progress bar and the counted percentage, the bar folds away once the file lands, and a check draws in.
• Reduced motion jumps progress and replaces height and blur swaps with fades.

Responsive behavior

• The dropzone and list fill their container; file names ellipsize on one line.
• On touch devices the dropzone opens the native file picker, since drag and drop is desktop only.

Performance

• Uploads run through your onUpload, one call per valid file; there is no concurrency limit, so queue large batches yourself.
• The file list is not virtualized; keep it to a reasonable number of files.

Notes for AI

• Use when files are uploaded with progress. Use file-dropzone when you only need to pick files without upload state.
• Wire onUpload to fetch or XHR and honour the AbortSignal; without onUpload files are only listed and validated.

Related

• File dropzone: A generous target for dropping one or more files.
• Progress: Show how much of a known task is complete.

Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt