File Upload

A component that is used to upload multiple files.

Drop your files here

Anatomy

<FileUpload.Root>
  <FileUpload.Label />
  <FileUpload.Dropzone>
    <FileUpload.Trigger />
  </FileUpload.Dropzone>
  <FileUpload.ItemGroup>
    <FileUpload.Item>
      <FileUpload.ItemPreview>
        <FileUpload.ItemPreviewImage />
      </FileUpload.ItemPreview>
      <FileUpload.ItemName />
      <FileUpload.ItemSizeText />
      <FileUpload.ItemDeleteTrigger />
    </FileUpload.Item>
  </FileUpload.ItemGroup>
  <FileUpload.ClearTrigger />
  <FileUpload.HiddenInput />
</FileUpload.Root>

Examples

Initial Files

Use the defaultAcceptedFiles prop to set the initial files in the file upload component.

Clear Trigger

Use the ClearTrigger to remove all uploaded files at once.

Dropzone

Use the Dropzone to enable drag-and-drop. It exposes a data-dragging attribute for styling.

Directory Upload

Use the directory prop to upload entire folders. Access file paths through file.webkitRelativePath.

When uploading directories with many files, set maxFiles to a higher value or remove it entirely to prevent rejections.

Accepted File Types

Use the accept prop to restrict file types. Accepts MIME types (image/png) or extensions (.pdf).

Error Handling

Set constraints with maxFiles, maxFileSize, minFileSize, and accept. Rejected files include error codes like TOO_MANY_FILES, FILE_INVALID_TYPE, FILE_TOO_LARGE, or FILE_EXISTS.

File Transformations

Use transformFiles to process files before they're added. Useful for image compression, format conversion, or resizing.

Field

Use Field to add helper text and error handling.

Root Provider

An alternative way to control the file upload is to use the RootProvider component and the useFileUpload hook. This way you can access the state and methods from outside the component.

Pasting Files

Use setClipboardFiles to enable pasting images from the clipboard.

Media Capture

Use capture to access the device camera. Set to "environment" for back camera or "user" for front camera.

Rejected Files

Access rejectedFiles from the context to display validation errors.

Guides

File Previews

Use ItemPreview with type matching to show appropriate previews based on file format.

type="image/*": Shows image thumbnails using ItemPreviewImage
type="video/*": For video file previews
type="application/pdf": For PDF files
type=".*": Generic fallback for any file type

<FileUpload.ItemPreview type="image/*">
  <FileUpload.ItemPreviewImage />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type="video/*">
  <VideoIcon />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type="application/pdf">
  <PdfIcon />
</FileUpload.ItemPreview>

<FileUpload.ItemPreview type=".*">
  <FileIcon />
</FileUpload.ItemPreview>

Disable Dropzone

To disable drag-and-drop functionality, set allowDrop to false.

<FileUpload.Root allowDrop={false}>{/* ... */}</FileUpload.Root>

Prevent Document Drop

By default, we prevent accidental navigation when files are dropped outside the dropzone. Set preventDocumentDrop to false to disable this.

<FileUpload.Root preventDocumentDrop={false}>{/* ... */}</FileUpload.Root>

Prevent Double Open

Use disableClick on Dropzone when delegating clicks to a nested Trigger. This prevents the file picker from opening twice.

<FileUpload.Dropzone disableClick>
  <FileUpload.Trigger>Choose Files</FileUpload.Trigger>
  Drag files here
</FileUpload.Dropzone>

API Reference

Props

Root

Renders a <div> element.

Prop	Default	Type
`accept`		`Record<string, string[]> \| FileMimeType \| FileMimeType[]` The accept file types
`acceptedFiles`		`File[]` The controlled accepted files
`allowDrop`	`true`	`boolean` Whether to allow drag and drop in the dropzone element
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`capture`		`'user' \| 'environment'` The default camera to use when capturing media
`defaultAcceptedFiles`		`File[]` The default accepted files when rendered. Use when you don't need to control the accepted files of the input.
`directory`		`boolean` Whether to accept directories, only works in webkit browsers
`disabled`		`boolean` Whether the file input is disabled
`ids`		`Partial<{ root: string dropzone: string hiddenInput: string trigger: string label: string item: (id: string) => string itemName: (id: string) => string itemSizeText: (id: string) => string itemPreview: (id: string) => string }>` The ids of the elements. Useful for composition.
`invalid`		`boolean` Whether the file input is invalid
`locale`	`'en-US'`	`string` The current locale. Based on the BCP 47 definition.
`maxFiles`	`1`	`number` The maximum number of files
`maxFileSize`	`Infinity`	`number` The maximum file size in bytes
`minFileSize`	`0`	`number` The minimum file size in bytes
`name`		`string` The name of the underlying file input
`onFileAccept`		`(details: FileAcceptDetails) => void` Function called when the file is accepted
`onFileChange`		`(details: FileChangeDetails) => void` Function called when the value changes, whether accepted or rejected
`onFileReject`		`(details: FileRejectDetails) => void` Function called when the file is rejected
`preventDocumentDrop`	`true`	`boolean` Whether to prevent the drop event on the document
`required`		`boolean` Whether the file input is required
`transformFiles`		`(files: File[]) => Promise<File[]>` Function to transform the accepted files to apply transformations
`translations`		`IntlTranslations` The localized messages to use.
`validate`		`(file: File, details: FileValidateDetails) => FileError[] \| null` Function to validate a file

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	root
`[data-disabled]`	Present when disabled
`[data-dragging]`	Present when in the dragging state

ClearTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	clear-trigger
`[data-disabled]`	Present when disabled

Dropzone

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`disableClick`		`boolean` Whether to disable the click event on the dropzone

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	dropzone
`[data-invalid]`	Present when invalid
`[data-disabled]`	Present when disabled
`[data-dragging]`	Present when in the dragging state

HiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

ItemDeleteTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	item-delete-trigger
`[data-disabled]`	Present when disabled
`[data-type]`	The type of the item

ItemGroup

Renders a <ul> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`type`		`ItemType`

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	item-group
`[data-disabled]`	Present when disabled
`[data-type]`	The type of the item

ItemName

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	item-name
`[data-disabled]`	Present when disabled
`[data-type]`	The type of the item

ItemPreviewImage

Renders a <img> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	item-preview-image
`[data-disabled]`	Present when disabled
`[data-type]`	The type of the item

ItemPreview

Renders a <img> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`type`	`'.*'`	`string` The file type to match against. Matches all file types by default.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	item-preview
`[data-disabled]`	Present when disabled
`[data-type]`	The type of the item

Item

Renders a <li> element.

Prop	Default	Type
`file`		`File`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	item
`[data-disabled]`	Present when disabled
`[data-type]`	The type of the item

ItemSizeText

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	item-size-text
`[data-disabled]`	Present when disabled
`[data-type]`	The type of the item

Label

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	label
`[data-disabled]`	Present when disabled
`[data-required]`	Present when required

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseFileUploadReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Trigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	file-upload
`[data-part]`	trigger
`[data-disabled]`	Present when disabled
`[data-invalid]`	Present when invalid

Context

API

Property	Type
`dragging`	`boolean` Whether the user is dragging something over the root element
`focused`	`boolean` Whether the user is focused on the dropzone element
`disabled`	`boolean` Whether the file input is disabled
`transforming`	`boolean` Whether files are currently being transformed via `transformFiles`
`openFilePicker`	`VoidFunction` Function to open the file dialog
`deleteFile`	`(file: File, type?: ItemType) => void` Function to delete the file from the list
`acceptedFiles`	`File[]` The accepted files that have been dropped or selected
`rejectedFiles`	`FileRejection[]` The files that have been rejected
`setFiles`	`(files: File[]) => void` Sets the accepted files
`clearFiles`	`VoidFunction` Clears the accepted files
`clearRejectedFiles`	`VoidFunction` Clears the rejected files
`getFileSize`	`(file: File) => string` Returns the formatted file size (e.g. 1.2MB)
`createFileUrl`	`(file: File, cb: (url: string) => void) => VoidFunction` Returns the preview url of a file. Returns a function to revoke the url.
`setClipboardFiles`	`(dt: DataTransfer) => boolean` Sets the clipboard files Returns `true` if the clipboard data contains files, `false` otherwise.