File Upload

new

Drop it like it's hot. Or click, or paste. We'll check its size first.

Demo

Open Props in the corner of the example to try size and disabled.

size on the root, xs to xl on the control scale. The icon circle is a control's height, the glyph a control's icon, and the zone's padding, the list rows and the Remove buttons scale with them. The zone is as tall as its content; give it a min-h-* class for a taller one.

Installation

Usage

<script setup lang="ts">
import { Upload } from '@lucide/vue'
import {
  FileUpload,
  FileUploadDescription,
  FileUploadDropzone,
  FileUploadIcon,
  FileUploadItem,
  FileUploadItemDelete,
  FileUploadItemMetadata,
  FileUploadItemPreview,
  FileUploadList,
  FileUploadTitle,
  FileUploadTrigger,
  fileKey,
} from '@/components/ui/file-upload'

const photo = ref<File | null>(null)
</script>

<template>
  <FileUpload v-slot="{ files }" v-model="photo" accept="image/*">
    <FileUploadDropzone as-child>
      <FileUploadTrigger>
        <FileUploadIcon><Upload /></FileUploadIcon>
        <FileUploadTitle>Drop your image here</FileUploadTitle>
        <FileUploadDescription>PNG or JPG, up to 2 MB</FileUploadDescription>
      </FileUploadTrigger>
    </FileUploadDropzone>
    <FileUploadList>
      <FileUploadItem v-for="file in files" :key="fileKey(file)" :file="file">
        <FileUploadItemPreview />
        <FileUploadItemMetadata />
        <FileUploadItemDelete />
      </FileUploadItem>
    </FileUploadList>
  </FileUpload>
</template>

v-model is a File, or null once it's cleared. Add multiple and it's a File[] instead, [] when empty. Every change hands you a new value, so watchers and form libraries notice it. The default slot always gives you files as an array, so one list template fits both.

Three ways in: the trigger opens the file dialog, the dropzone takes drops, and Ctrl+V pastes while focus is inside. All three go through the same checks.

Give it a name, and the files submit with the form like a plain <input type="file">. The hidden input always holds exactly the files on screen, including the ones that were dropped or removed, so FormData and required never disagree with what the user sees. A form reset puts back the default-value files, or none.

Anatomy

FileUpload holds the files and the checks; the other parts are where they show.

  • FileUploadTrigger is the one way in from the keyboard: a real button that opens the dialog. Make it a Button with as-child.
  • FileUploadDropzone takes drops, and a click on it opens the dialog too. It is never a tab stop of its own. With as-child on the trigger, the whole zone is one button, as above. Put a trigger inside it instead to get a zone with a Browse button.
  • FileUploadIcon, FileUploadTitle and FileUploadDescription fill the zone. Inside the trigger, the title is the button's name and the description its description.
  • FileUploadList shows the files as rows or tiles, and nothing while there are none. Each FileUploadItem takes a file; key it with fileKey(file), since two files can share a name. FileUploadItemPreview, FileUploadItemMetadata and FileUploadItemDelete read the file from their item.
  • FileUploadClear removes every file.

Examples

Multiple

With multiple, new files join the list instead of replacing the old one. A file that is already there, same name, size and date, is turned away as a duplicate.

Multiple

Rejected files

accept, max-size and max-files keep files out of the model. The dialog's own filter is only a hint: the user can pick "All files", and a drop or a paste ignores it. So the component checks every file itself. accept takes MIME types, type/* and .ext, the same list the input does.

Whatever doesn't get in comes back through reject, once per pick, drop or paste, as { file, reason }. The reason is type, size, count, duplicate or directory (a folder dropped in). Say why, or the user is left wondering where their file went.

Rejections

Button

Leave the dropzone out and the trigger is all there is: an as-child Button, with the files listed under it. For a photo picker, show the picked image in the Button with urlOf from the default slot and put your own Remove on its corner.

Button
Team photoSquare images look best.

Layouts

layout="list" on FileUploadList shows each file as a row with a name and a size; grid as a tile with its picture. Tiles without a picture keep their name, since a grid of identical document icons tells nobody anything.

The list goes wherever you put it: after the zone, or inside it, where it is part of the drop target.

Layouts
  • sunset.svg228 B
  • forest.svg228 B
  • itinerary.pdf180 KB
  • sunset.svg228 B
  • forest.svg228 B
  • itinerary.pdf180 KB
  • sunset.svg228 B
  • forest.svg228 B
  • itinerary.pdf180 KB
  • sunset.svg228 B
  • forest.svg228 B
  • itinerary.pdf180 KB

Variants

The dropzone's frame comes outline (dashed), soft (filled) or subtle (both).

Variants

Field

Inside a Field the trigger takes the field's id, so clicking the label opens the dialog. It also takes the description, the error and the field's invalid, disabled and required state. Press Apply without a file.

Field

We only share it with the hiring team.

Not needed for this role.

Form validation

Bind v-model to a Formisch field and let a Valibot schema check the files: v.file() for one, v.array(v.file()) for many, with v.mimeType() and v.maxSize(). A schema error on one file has a path like ['floorPlans', 1]; show it in that file's FileUploadItemMetadata. Formisch focuses the first invalid field on submit, so pass it the element the trigger rendered: put the ref on FileUploadTrigger, or on the FileUploadDropzone that is the trigger through as-child.

The built-in checks run first. Leave max-size off if the schema should own that message.

Form

PDFs up to 5 MB each, three at most.

Upload progress

The component never uploads anything; it holds files. To upload as soon as files arrive, watch the model, start an upload for each new file, and draw its progress in FileUploadItemMetadata. Removing a file is the cancel button.

Progress

Existing files

The model holds Files only, so a photo that's already on the server can't go in it. Show it yourself while the model is empty. Here a frameless dropzone holds an Avatar, a Change trigger and a Remove button; a drop on the avatar counts, and the avatar rings while a file is dragged over it.

Avatar
AL

Drop an image on the photo, or press Change. Up to 2 MB.

Browse button

A dropzone that holds its content and an as-child trigger: the zone takes drops and clicks, the Browse button takes focus. FileUploadClear makes the Remove all button.

Custom
Drag and drop your dataset

Drop anywhere

A drop outside a dropzone opens the file in the browser, and the component doesn't touch the page to stop that. For a page-wide drop, listen on window yourself, call preventDefault on dragover and drop, and hand the files to the exposed addFiles, which runs the same checks.

Page drop

Known limits

  • Files only. A file already on the server can't sit in the model; see Existing files. Nuxt UI is working out a shape for this in nuxt/ui#6927; widening the model later won't break yours.
  • Nothing is announced when files are added, removed or rejected, and the Remove label is English. Use reject and a role="status" region as in Rejected files, and your own button calling removeFile for another language.
  • required reaches assistive tech only through the label and the browser's own message: aria-required isn't allowed on a button.
  • open() works only straight from a click or a key press. After an await or a timer, the browser blocks the dialog without a word.
  • Safari doesn't say what's being dragged until the drop, so a file that will be rejected looks welcome until then.
  • Safari before 14.1 can't put dropped files into the hidden input. v-model still works; native form submission misses them.
  • Long lists aren't virtualized. File lists rarely run past a few dozen.

API Reference

fileKey(file), acceptsFile(file, accept), formatFileSize(bytes) and gateFiles(...), the checks the component runs, are exported from the same module.

Data attributes

With as-child the outer part's data-slot wins: the zone that is the trigger carries file-upload-dropzone, and a Button trigger carries file-upload-trigger.

data-slotAttributesDescription
file-uploaddata-size, data-dragging, data-disabled, data-invalid, data-emptyThe root. data-dragging is set while files are dragged over a dropzone, data-invalid when the field, aria-invalid or a failed native required check marks it.
file-upload-input—The hidden <input type="file">, carrying name, accept, multiple, required and the files.
file-upload-dropzonedata-variant, data-dragging, data-disabled, data-invalidThe part that takes drops.
file-upload-trigger—The button that opens the dialog.
file-upload-icon—The icon circle.
file-upload-title—The zone's main line.
file-upload-description—The zone's second line.
file-upload-listdata-layoutThe files, a role="list".
file-upload-itemdata-imageOne file. data-image is set when it has a thumbnail.
file-upload-item-previewdata-imageThe thumbnail or the file icon.
file-upload-item-content—FileUploadItemMetadata: the name and size.
file-upload-item-name—The file name.
file-upload-item-size—The file size.
file-upload-item-delete—The Remove button. After a removal, focus moves to the next one, the previous one, then the trigger.
file-upload-clear—The button that removes every file.

Accessibility

The trigger is a real <button type="button">, so it never submits a form, and Enter and Space work without any key handling of ours. The dropzone is not a tab stop: inside it, a trigger is, so keyboard users get one stop per component, not two. The list, its Remove buttons and the hidden input sit outside the trigger, because anything interactive inside a button disappears for screen readers.

The description is read once, as the trigger's description, not again as part of its name.

Each Remove button is labelled "Remove" and the file name. After a removal, focus moves to the next file's Remove button, then the previous one, then the trigger, so removing several files in a row is a few presses of Enter.

The hidden input is aria-hidden and out of the tab order. When a required upload is empty, the browser focuses it to show its message; the dropzone shows that focus, and Tab moves on to the trigger.

KeyAction
TabMoves to the trigger, then to each Remove button. The dropzone is not a stop.
Enter / SpaceOn the trigger, opens the file dialog. On a Remove button, removes that file.
Ctrl+V / Cmd+VWith focus inside the component, adds files from the clipboard, a keyboard alternative to dragging. Off with :paste="false".

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. registry 0.21.0

    7940e7c — FileUpload's parts follow its size through CSS variables on the root instead of reading it from the context: --file-upload-gap, --file-upload-padding, --file-upload-control, --file-upload-icon, --file-upload-remove-icon, and --file-upload-title, --file-upload-description and --file-upload-name with their -leading twins. A class on a part now wins over its size, and one variable on the root retunes every part. Nothing moves by a pixel. The size-free styles are plain strings now: fileUploadIcon, fileUploadTitle, fileUploadDescription, fileUploadItemName and fileUploadRemoveOverlay replace the …Variants functions, and the dropzone, list, item and preview variants lost their size key.

  4. registry 0.14.0

    2add2d3 — FileUpload is built from parts, after Dice UI's anatomy: FileUpload (the files, the checks, the hidden input, paste, Field wiring and size), FileUploadDropzone (drops and a click, variant), FileUploadTrigger (the button that opens the dialog, as-child for a Button), FileUploadIcon, FileUploadTitle, FileUploadDescription, FileUploadList (layout list or grid), FileUploadItem, FileUploadItemPreview, FileUploadItemMetadata, FileUploadItemDelete and FileUploadClear, plus fileKey(file) for v-for keys. The zone that is one button is FileUploadDropzone as-child on the trigger; a zone with a Browse button holds an as-child trigger and is no tab stop itself. The props mode, layout, position, label, description, icon, file-icon, file-image, file-delete, preview, interactive and dropzone, the 14 slots and the exposed triggerEl are gone: compose the parts instead, and put a ref on the trigger for Formisch. removeFile takes the file, not an index. A trigger without a dropzone no longer takes drops.

  5. registry 0.13.2

    e5cbc67 — FileUpload exposes the element that takes focus as triggerEl instead of triggerRef. In a Nuxt project the auto-imported Vue triggerRef is typed on every component instance, so triggerRef on a template ref read as a function and the Formisch example failed to type-check.

  6. registry 0.13.0

    277f092 — New FileUpload: a drop zone (mode="area") or a Button (mode="button") that picks files into a File or, with multiple, a File[] v-model. Files come from the dialog, a drop or a paste, and all three go through accept, max-size and max-files, so a file of the wrong type never reaches the model even when the user picks "All files" in the dialog; whatever is turned away comes back through reject with a reason. Files show as a list or a grid of thumbnails, under the frame or inside it, with a Remove button each that moves focus to the next one. The hidden file input always holds the files on screen, so name submits them with a native form, required blocks an empty one, and a form reset puts back the starting files. A file drag is always taken, even a rejected one, so the browser never opens the file in place of the page. Five sizes on the control scale, outline, soft and subtle frames, Field wiring, and slots for every part, including triggerAttrs for your own button.