File Upload

A drop zone or button for choosing files, and a list of the files chosen.

import { UploadIcon } from "lucide-react";

import {
  FileUpload,
  FileUploadDropzone,
  FileUploadItem,
  FileUploadItemMetadata,
  FileUploadItemPreview,
  FileUploadItemRemove,
  FileUploadList,
  formatFileSize,
} from "@/components/ui/file-upload";

const maxSize = 10_000_000;

export default function FileUploadBasic() {
  return (
    <FileUpload multiple accept="image/*,.pdf" maxSize={maxSize} className="max-w-sm">
      <FileUploadDropzone>
        <UploadIcon />
        <span className="font-medium text-foreground">Drop files or click to browse</span>
        <span className="text-2xs">Images and PDFs, up to {formatFileSize(maxSize)}</span>
      </FileUploadDropzone>
      <FileUploadList>
        {(file) => (
          <FileUploadItem file={file}>
            <FileUploadItemPreview />
            <FileUploadItemMetadata />
            <FileUploadItemRemove />
          </FileUploadItem>
        )}
      </FileUploadList>
    </FileUpload>
  );
}

Installation

Add the registryOnce per project
pnpm dlx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
Add file-upload
pnpm dlx shadcn@latest add @jarvis/file-upload

Usage

import { UploadIcon } from "lucide-react";

import {
  FileUpload,
  FileUploadDropzone,
  FileUploadItem,
  FileUploadItemMetadata,
  FileUploadItemPreview,
  FileUploadItemRemove,
  FileUploadList,
} from "@/components/ui/file-upload";

export function Attachments() {
  return (
    <FileUpload multiple accept="image/*,.pdf">
      <FileUploadDropzone>
        <UploadIcon />
        <span className="font-medium text-foreground">Drop files or click to browse</span>
      </FileUploadDropzone>
      <FileUploadList>
        {(file) => (
          <FileUploadItem file={file}>
            <FileUploadItemPreview />
            <FileUploadItemMetadata />
            <FileUploadItemRemove />
          </FileUploadItem>
        )}
      </FileUploadList>
    </FileUpload>
  );
}

FileUpload holds the chosen files as File objects. It doesn't upload them: send them yourself, or give it a name to submit them with a form.

FileUploadDropzone accepts dropped files and opens the file picker on click. It's a button, so use spans inside it. FileUploadList renders its child for each file. FileUploadItemMetadata shows the file's name and size, and cuts a long name in the middle with Truncate, so its extension stays in sight.

accept, maxSize and maxFiles reject files, and onFileReject tells you which and why.

Composition

FileUpload

Examples

Upload progress

Put a FileUploadItemProgress in FileUploadItemMetadata to show progress while a file uploads.

import { UploadIcon } from "lucide-react";
import * as React from "react";

import {
  FileUpload,
  FileUploadDropzone,
  FileUploadItem,
  FileUploadItemMetadata,
  FileUploadItemPreview,
  FileUploadItemProgress,
  FileUploadItemRemove,
  FileUploadList,
} from "@/components/ui/file-upload";

// Stands in for a real upload, which would report progress from XMLHttpRequest's upload events.
function fakeUpload(onProgress: (percent: number) => void) {
  let percent = 0;
  const timer = setInterval(() => {
    percent = Math.min(percent + 6 + Math.random() * 14, 100);
    onProgress(Math.round(percent));
    if (percent === 100) clearInterval(timer);
  }, 300);
}

export default function FileUploadWithProgress() {
  const [files, setFiles] = React.useState<File[]>([]);
  const [progress, setProgress] = React.useState(() => new Map<File, number>());

  function addFiles(next: File[]) {
    for (const file of next) {
      if (files.includes(file)) continue;
      fakeUpload((percent) => setProgress((current) => new Map(current).set(file, percent)));
    }
    setFiles(next);
  }

  return (
    <FileUpload multiple value={files} onValueChange={addFiles} className="max-w-sm">
      <FileUploadDropzone>
        <UploadIcon />
        <span className="font-medium text-foreground">Drop files or click to browse</span>
      </FileUploadDropzone>
      <FileUploadList>
        {(file) => {
          const percent = progress.get(file) ?? 0;
          return (
            <FileUploadItem file={file}>
              <FileUploadItemPreview />
              <FileUploadItemMetadata>
                {percent < 100 ? <FileUploadItemProgress value={percent} /> : null}
              </FileUploadItemMetadata>
              <FileUploadItemRemove />
            </FileUploadItem>
          );
        }}
      </FileUploadList>
    </FileUpload>
  );
}

With a label

Point a FieldLabel at the dropzone's id, or leave out htmlFor and the label names the dropzone and the trigger itself. Set invalid on the Field and explain a rejected file with a FieldError. The dropzone and the trigger read out the field's FieldDescription and FieldError, and turn invalid or disabled with the field.

import { UploadIcon } from "lucide-react";
import * as React from "react";

import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import {
  FileUpload,
  FileUploadDropzone,
  FileUploadItem,
  FileUploadItemMetadata,
  FileUploadItemPreview,
  FileUploadItemRemove,
  FileUploadList,
} from "@/components/ui/file-upload";

export default function FileUploadWithField() {
  const [error, setError] = React.useState<string | null>(null);

  return (
    <Field invalid={!!error} className="w-full max-w-sm">
      <FieldLabel htmlFor="contacts-file">Import contacts</FieldLabel>
      <FileUpload
        accept=".csv"
        maxSize={5_000_000}
        onValueChange={() => setError(null)}
        onFileReject={(file, reason) =>
          setError(
            reason === "type" ? `${file.name} isn't a CSV file.` : `${file.name} is over 5 MB.`,
          )
        }
      >
        <FileUploadDropzone id="contacts-file">
          <UploadIcon />
          <span className="font-medium text-foreground">Drop a CSV file or click to browse</span>
        </FileUploadDropzone>
        <FileUploadList>
          {(file) => (
            <FileUploadItem file={file}>
              <FileUploadItemPreview />
              <FileUploadItemMetadata />
              <FileUploadItemRemove />
            </FileUploadItem>
          )}
        </FileUploadList>
      </FileUpload>
      {error ? (
        <FieldError>{error}</FieldError>
      ) : (
        <FieldDescription>One contact per row, up to 5 MB.</FieldDescription>
      )}
    </Field>
  );
}

In a form

Give a Field or the upload a name, and the files submit under it, each as its own value, so formData.getAll(name) returns them. Pass form with a form's id when the upload sits outside it. With required, the form won't submit without a file, which fails as valueMissing. A form reset brings back defaultValue. A Form's onFormSubmit gets the File objects as an array.

import { UploadIcon } from "lucide-react";

import { Button } from "@/components/ui/button";
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import {
  FileUpload,
  FileUploadDropzone,
  FileUploadItem,
  FileUploadItemMetadata,
  FileUploadItemPreview,
  FileUploadItemRemove,
  FileUploadList,
} from "@/components/ui/file-upload";
import { Form } from "@/components/ui/form";
import { toast } from "@/components/ui/toast";

export default function FileUploadForm() {
  return (
    <Form
      className="w-full max-w-sm"
      onFormSubmit={(values) => {
        const [resume] = values.resume as File[];
        toast.add({ title: "Application sent", description: `With ${resume?.name}.` });
      }}
    >
      <Field name="resume">
        <FieldLabel>Résumé</FieldLabel>
        <FileUpload accept=".pdf" required>
          <FileUploadDropzone>
            <UploadIcon />
            <span className="font-medium text-foreground">Drop a PDF or click to browse</span>
          </FileUploadDropzone>
          <FileUploadList>
            {(file) => (
              <FileUploadItem file={file}>
                <FileUploadItemPreview />
                <FileUploadItemMetadata />
                <FileUploadItemRemove />
              </FileUploadItem>
            )}
          </FileUploadList>
        </FileUpload>
        <FieldDescription>One PDF, sent with your application.</FieldDescription>
        <FieldError match="valueMissing">Add your résumé.</FieldError>
      </Field>
      <Button type="submit" variant="primary" className="self-start">
        Send application
      </Button>
    </Form>
  );
}

With a button

FileUploadTrigger opens the file picker from a button, when a drop zone would take too much room.

import { PaperclipIcon } from "lucide-react";

import {
  FileUpload,
  FileUploadItem,
  FileUploadItemMetadata,
  FileUploadItemPreview,
  FileUploadItemRemove,
  FileUploadList,
  FileUploadTrigger,
} from "@/components/ui/file-upload";

export default function FileUploadWithButton() {
  return (
    <FileUpload multiple maxFiles={3} className="max-w-sm">
      <FileUploadTrigger>
        <PaperclipIcon />
        Attach files
      </FileUploadTrigger>
      <FileUploadList>
        {(file) => (
          <FileUploadItem file={file}>
            <FileUploadItemPreview />
            <FileUploadItemMetadata />
            <FileUploadItemRemove />
          </FileUploadItem>
        )}
      </FileUploadList>
    </FileUpload>
  );
}

Disabled

import { UploadIcon } from "lucide-react";

import { FileUpload, FileUploadDropzone } from "@/components/ui/file-upload";

export default function FileUploadDisabled() {
  return (
    <FileUpload disabled className="max-w-sm">
      <FileUploadDropzone>
        <UploadIcon />
        <span className="font-medium text-foreground">Uploads are paused</span>
        <span className="text-2xs">Your workspace is out of storage.</span>
      </FileUploadDropzone>
    </FileUpload>
  );
}

Props

The file also exports formatFileSize(bytes), which returns a size such as "2.4 MB".

Part	Extends
FileUpload	<div>
FileUploadDropzone	<button>
FileUploadTrigger	Button
FileUploadList	<ul>
FileUploadItem	<li>
FileUploadItemPreview	<span>
FileUploadItemMetadata	<div>
FileUploadItemProgress	Base UI's Progress.Root
FileUploadItemRemove	Button

The tables leave out className, style and render. Parts built on Base UI take them as its styling and composition guides describe.

FileUpload

Prop	Type	Default
`value` The chosen files.	`File[]`	—
`defaultValue`	`File[]`	—
`onValueChange` Called with every file after one is added or removed, and with `defaultValue` when the form resets.	`((files: File[]) => void)`	—
`accept` File types to take, as for a file input: extensions such as `.pdf`, or types such as `image/*`.	`string`	—
`multiple` Whether people can choose more than one file. Without it, a new file replaces the last.	`boolean`	`false`
`maxFiles` The most files to take at once, with `multiple`.	`number`	—
`maxSize` The largest file to take, in bytes.	`number`	—
`onFileReject` Called for each file turned away, with why: its `type`, its `size`, or the file `count`.	`((file: File, reason: FileRejectReason) => void)`	—
`disabled`	`boolean`	`false`
`name` The name the files submit under in a form. A `Field`'s `name` takes its place.	`string`	—
`form` The `id` of the form to submit the files with, when the upload isn't inside it.	`string`	—
`required` Whether a form can't be submitted without a file.	`boolean`	`false`

FileUploadTrigger

Prop	Type	Default
`focusableWhenDisabled` Whether the button should be focusable when disabled.	`boolean`	`false`
`nativeButton` Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).	`boolean`	`true`
`variant`	`"destructive" \| "ghost" \| "link" \| "outline" \| "primary" \| "secondary"`	`"secondary"`
`size`	`"default" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xs" \| "lg" \| "sm" \| "xs"`	`"default"`

FileUploadList

Prop	Type	Default
`children` Renders each file, usually as a `FileUploadItem`.	`(file: File, index: number) => React.ReactNode`	—

FileUploadItem

Prop	Type	Default
`file` The file this item shows.	`File`	—

FileUploadItemProgress

Prop	Type	Default
`aria-valuetext` A string value that provides a user-friendly name for `aria-valuenow`, the current value of the progress bar.	`string`	—
`format` Options to format the value.	`Intl.NumberFormatOptions`	—
`getAriaValueText` Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar.	`((formattedValue: string, value: number \| null) => string)`	—
`locale` The locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale.	`Intl.LocalesArgument`	—
`max` The maximum value.	`number`	`100`
`min` The minimum value.	`number`	`0`
`value` The current value. The component is indeterminate when value is `null`.	`number \| null`	—

FileUploadItemRemove

Prop	Type	Default
`focusableWhenDisabled` Whether the button should be focusable when disabled.	`boolean`	`false`
`nativeButton` Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).	`boolean`	`true`
`variant`	`"destructive" \| "ghost" \| "link" \| "outline" \| "primary" \| "secondary"`	`"ghost"`
`size`	`"default" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xs" \| "lg" \| "sm" \| "xs"`	`"icon-sm"`