File Upload
newDrop it like it's hot. Or click, or paste. We'll check its size first.
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.
FileUploadTriggeris the one way in from the keyboard: a real button that opens the dialog. Make it a Button withas-child.FileUploadDropzonetakes drops, and a click on it opens the dialog too. It is never a tab stop of its own. Withas-childon 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,FileUploadTitleandFileUploadDescriptionfill the zone. Inside the trigger, the title is the button's name and the description its description.FileUploadListshows the files as rows or tiles, and nothing while there are none. EachFileUploadItemtakes afile; key it withfileKey(file), since two files can share a name.FileUploadItemPreview,FileUploadItemMetadataandFileUploadItemDeleteread the file from their item.FileUploadClearremoves 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.
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.
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.
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.
Variants
The dropzone's frame comes outline (dashed), soft (filled) or subtle (both).
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.
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.
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.
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.
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.
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.
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
rejectand arole="status"region as in Rejected files, and your own button callingremoveFilefor another language. requiredreaches assistive tech only through the label and the browser's own message:aria-requiredisn't allowed on a button.open()works only straight from a click or a key press. After anawaitor 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-modelstill works; native form submission misses them. - Long lists aren't virtualized. File lists rarely run past a few dozen.
API Reference
FileUpload
| Prop | Default | Type and description |
|---|---|---|
| multiple | — | MHolds a list of files instead of one. New files are added to the list; without it, a new file replaces the old one. Changing it converts the value, and files that no longer fit are reported through |
| defaultValue | — | FileUploadModel<M>The starting files when |
| accept | — | stringThe file types allowed: MIME types, |
| maxFiles | — | numberWith |
| maxSize | — | numberThe largest file allowed, in bytes. Bigger files are rejected with |
| paste | true | booleanTakes files pasted with Ctrl+V or Cmd+V while focus is inside the component. |
| size | "md" | FileUploadSizeFrom |
| id | — | stringOverrides the |
| name | — | stringSubmits the files with the form under this name. The hidden file input always holds exactly the files shown. |
| form | — | stringThe |
| capture | — | "user" | "environment"On phones, opens the camera instead of the file dialog: |
| disabled | — | booleanDisables the trigger, the Remove buttons and the hidden input, and ignores drops and pastes. Also set by a disabled field. |
| required | — | booleanMarks the hidden file input required, so a form with no file fails native validation. Also set by a required field. |
| modelValue | — | FileUploadModel<M>The picked files, bound with |
| Event | Payload and description |
|---|---|
| reject | [rejections: FileUploadRejection[]]Fires once per pick, drop or paste with the files that were turned away, each as |
| update:modelValue | [value: FileUploadModel<M> | undefined]Fires when files are added or removed, with the new |
| Slot | Scope and description |
|---|---|
| default | { files: File[]; open: () => void; clear: () => void; removeFile: (file: File) => void; addFiles: (files: FileList | File[]) => void; urlOf: (file: File) => string | undefined; dragging: boolean; invalid: boolean; }The parts. Receives |
| Member | Type and description |
|---|---|
| open | () => voidOpens the file dialog. Browsers allow this only straight from a user's click or key press. |
| clear | () => voidRemoves every file. |
| addFiles | (files: FileList | File[]) => voidAdds files from your own source, such as a drop on the whole page, through the same checks and |
| removeFile | (file: File) => voidRemoves a file and moves focus to the next Remove button, the previous one, or the trigger. |
| inputRef | HTMLInputElement | nullThe hidden file input. |
FileUploadDropzone
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead, merging the frame and the drop handling onto it. On a |
| as | "div" | AsTag | ComponentThe element or component to render. |
| variant | "outline" | FileUploadVariantThe frame: a dashed |
| Slot | Scope and description |
|---|---|
| default | { dragging: boolean; }The zone's content. Receives |
FileUploadTrigger
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a button, such as a Button, merging the trigger's id, state and click onto it. |
| as | "button" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The trigger's content, or with |
FileUploadIcon
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead, merging the icon circle's attributes onto it. |
| as | "span" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The icon, in a circle sized from the root and lifted off a filled frame. |
FileUploadTitle
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead, merging the title's attributes onto it. |
| as | "span" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The zone's main line. Inside the trigger it is the button's name. |
FileUploadDescription
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead, merging the description's attributes onto it. |
| as | "span" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The zone's second line. The trigger reads it through |
FileUploadList
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a list, merging the list's attributes onto it. |
| as | "ul" | AsTag | ComponentThe element or component to render. |
| layout | "list" | FileUploadLayout
|
| Slot | Scope and description |
|---|---|
| default | {}The items. The list renders nothing while there are no files. |
FileUploadItem
| Prop | Default | Type and description |
|---|---|---|
| file* | — | FileThe file this item shows. Its parts read it from here. |
| asChild | — | booleanRender the single child instead of a list item, merging the item's attributes onto it. |
| as | "li" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | { file: File; url: string | undefined; }The item's parts. Receives |
FileUploadItemPreview
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead, merging the preview's attributes onto it. |
| as | "div" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | { file: File; url: string | undefined; }Replaces the thumbnail of an image file, or the file icon of another. Receives |
FileUploadItemMetadata
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead, merging the metadata's attributes onto it. |
| as | "div" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | { file: File; size: string; }Replaces the name and size lines, a good place for progress or an error. Receives |
FileUploadItemDelete
| Slot | Scope and description |
|---|---|
| default | {}The button's icon, an X by default. |
FileUploadClear
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a button, such as a Button, merging the clear action onto it. |
| as | "button" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The button's content. |
Props
- multiple
MHolds a list of files instead of one. New files are added to the list; without it, a new file replaces the old one. Changing it converts the value, and files that no longer fit are reported throughreject.- defaultValue
FileUploadModel<M>The starting files whenv-modelis not used. A native form reset puts them back.- accept
stringThe file types allowed: MIME types,type/*wildcards and.extextensions, comma-separated. Checked on every file from the dialog, a drop or a paste, since the dialog's own filter is only a hint.- maxFiles
numberWithmultiple, the most files the list holds. Files past it are rejected withcount.- maxSize
numberThe largest file allowed, in bytes. Bigger files are rejected withsize.- paste
true booleanTakes files pasted with Ctrl+V or Cmd+V while focus is inside the component.- size
"md" FileUploadSizeFromxstoxlon the control scale: the zone's icon, padding and gaps, and the list's rows, tiles and Remove buttons.- id
stringOverrides theidtaken from a surrounding field. It lands on the trigger, so the field's label opens the dialog.- name
stringSubmits the files with the form under this name. The hidden file input always holds exactly the files shown.- form
stringTheidof a form elsewhere on the page to submit the files with.- capture
"user" | "environment"On phones, opens the camera instead of the file dialog:userfor the front camera,environmentfor the back one.- disabled
booleanDisables the trigger, the Remove buttons and the hidden input, and ignores drops and pastes. Also set by a disabled field.- required
booleanMarks the hidden file input required, so a form with no file fails native validation. Also set by a required field.- modelValue
FileUploadModel<M>The picked files, bound withv-model: aFileornull, or aFile[]withmultiple. Every change is a new value, never a mutated array.
Emits
- reject
[rejections: FileUploadRejection[]]Fires once per pick, drop or paste with the files that were turned away, each as{ file, reason }. The reason istype,size,count,duplicateordirectory.- update:modelValue
[value: FileUploadModel<M> | undefined]Fires when files are added or removed, with the newFile,nullorFile[].
Slots
- default
{ files: File[]; open: () => void; clear: () => void; removeFile: (file: File) => void; addFiles: (files: FileList | File[]) => void; urlOf: (file: File) => string | undefined; dragging: boolean; invalid: boolean; }The parts. Receivesfiles(always an array, even withoutmultiple),open,clear,removeFile,addFiles,urlOf(the thumbnail URL of an image file, made once the page runs in the browser),draggingandinvalid.
Exposed
- open
() => voidOpens the file dialog. Browsers allow this only straight from a user's click or key press.- clear
() => voidRemoves every file.- addFiles
(files: FileList | File[]) => voidAdds files from your own source, such as a drop on the whole page, through the same checks andrejectas a drop.- removeFile
(file: File) => voidRemoves a file and moves focus to the next Remove button, the previous one, or the trigger.- inputRef
HTMLInputElement | nullThe hidden file input.
Props
- asChild
booleanRender the single child instead, merging the frame and the drop handling onto it. On aFileUploadTriggerit makes the whole zone one button.- as
"div" AsTag | ComponentThe element or component to render.- variant
"outline" FileUploadVariantThe frame: a dashedoutline, a filledsoft, orsubtle, both.
Slots
- default
{ dragging: boolean; }The zone's content. Receivesdragging.
Props
- asChild
booleanRender the single child instead of a button, such as a Button, merging the trigger's id, state and click onto it.- as
"button" AsTag | ComponentThe element or component to render.
Slots
- default
{}The trigger's content, or withas-childthe element that opens the dialog.
Props
- asChild
booleanRender the single child instead, merging the icon circle's attributes onto it.- as
"span" AsTag | ComponentThe element or component to render.
Slots
- default
{}The icon, in a circle sized from the root and lifted off a filled frame.
Props
- asChild
booleanRender the single child instead, merging the title's attributes onto it.- as
"span" AsTag | ComponentThe element or component to render.
Slots
- default
{}The zone's main line. Inside the trigger it is the button's name.
Props
- asChild
booleanRender the single child instead, merging the description's attributes onto it.- as
"span" AsTag | ComponentThe element or component to render.
Slots
- default
{}The zone's second line. The trigger reads it througharia-describedby, so it is not read twice as part of the button's name.
Props
- asChild
booleanRender the single child instead of a list, merging the list's attributes onto it.- as
"ul" AsTag | ComponentThe element or component to render.- layout
"list" FileUploadLayoutlistshows each file as a row with its name and size;gridas a square tile, with the picture when there is one.
Slots
- default
{}The items. The list renders nothing while there are no files.
Props
- file*
FileThe file this item shows. Its parts read it from here.- asChild
booleanRender the single child instead of a list item, merging the item's attributes onto it.- as
"li" AsTag | ComponentThe element or component to render.
Slots
- default
{ file: File; url: string | undefined; }The item's parts. Receivesfileand the thumbnailurl.
Props
- asChild
booleanRender the single child instead, merging the preview's attributes onto it.- as
"div" AsTag | ComponentThe element or component to render.
Slots
- default
{ file: File; url: string | undefined; }Replaces the thumbnail of an image file, or the file icon of another. Receivesfileandurl.
Props
- asChild
booleanRender the single child instead, merging the metadata's attributes onto it.- as
"div" AsTag | ComponentThe element or component to render.
Slots
- default
{ file: File; size: string; }Replaces the name and size lines, a good place for progress or an error. Receivesfileand its formattedsize.
Slots
- default
{}The button's icon, an X by default.
Props
- asChild
booleanRender the single child instead of a button, such as a Button, merging the clear action onto it.- as
"button" AsTag | ComponentThe element or component to render.
Slots
- default
{}The button's content.
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-slot | Attributes | Description |
|---|---|---|
| file-upload | data-size, data-dragging, data-disabled, data-invalid, data-empty | The 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-dropzone | data-variant, data-dragging, data-disabled, data-invalid | The 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-list | data-layout | The files, a role="list". |
| file-upload-item | data-image | One file. data-image is set when it has a thumbnail. |
| file-upload-item-preview | data-image | The 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.
| Key | Action |
|---|---|
| Tab | Moves to the trigger, then to each Remove button. The dropzone is not a stop. |
| Enter / Space | On the trigger, opens the file dialog. On a Remove button, removes that file. |
| Ctrl+V / Cmd+V | With focus inside the component, adds files from the clipboard, a keyboard alternative to dragging. Off with :paste="false". |