Skip to content
Mosaic
On this page

FileUpload

Headless, unstyled file picker and drop zone. Owns a hidden <input type="file">, checks each file against accept and maxSize for the picker and for drops, and reports the rest through onReject. FileUpload.useFileUpload() reads the files and actions inside the root; FileUpload.useObjectUrl(file) gives a preview URL that is revoked when the file changes or the caller unmounts.

Use for

  • a file picker behind your own button
  • a drag and drop zone for files
  • a metadata or key file upload
  • a list of picked files with image thumbnails and remove buttons

Practices

GuidancePractice
Don’tUse it for an avatar or logo row. Use AvatarUpload instead.
Don’tRender your own <input type="file">. The root owns one.
DoShow feedback from onReject. A rejected file is never added, while the accepted files in the same batch are.
DoTreat data-drag-rejected as a hint. During a drag the browser hides file names, so extension-only accept entries and blank types are not flagged.
DoUse FileUpload.useObjectUrl to show a picked image in your own element, instead of URL.createObjectURL by hand.

API reference

FileUpload.Root

Holds the selected files and the hidden input. Renders a div, or the render element, with data-empty and data-disabled. In single mode a new pick replaces the file; in multiple mode picks append.

PropTypeDescription
valueFile[]The selected files, when controlled.
defaultValueFile[]The selected files on mount, when uncontrolled.Default: []
onValueChange(files: File[]) => voidCalled with the full file list whenever it changes.
multiplebooleanAllows more than one file.Default: false
acceptstringNative accept string, such as image/*,.pdf. Also applied to drops.
maxSizenumberLargest size in bytes for one file.
onReject(rejections: FileRejection[]) => voidCalled with each rejected file and its reason: accept, size, or overflow for extra files in single mode.
disabledbooleanDisables the trigger, the drop zone and the picker.Default: false
inputIdstringThe hidden input id, so a <label htmlFor> opens the picker.Default: a generated id

FileUpload.Trigger

A button that opens the native picker. Carries data-disabled.

FileUpload.Dropzone

A div that takes dropped files and ignores drags that carry none. Carries data-dragging, data-drag-rejected and data-disabled.

FileUpload.Item

Wraps one picked file for ItemPreview and ItemDelete. Carries data-image for an image file.

PropTypeDescription
fileFileThe file it represents, usually from useFileUpload().files.

FileUpload.ItemPreview

An img of the item's file, with the file name as alt. Renders nothing for a file that is not an image.

FileUpload.ItemDelete

A button that removes the item's file. Carries data-disabled.

Examples

A drop zone with a file list

TSX
<FileUpload.Root accept='image/*' multiple onReject={showRejections}>
  <FileUpload.Dropzone>
    <FileUpload.Trigger>Choose files</FileUpload.Trigger>
  </FileUpload.Dropzone>
  <FileList />
</FileUpload.Root>

function FileList() {
  const { files } = FileUpload.useFileUpload();
  return files.map(file => (
    <FileUpload.Item key={file.name} file={file}>
      <FileUpload.ItemPreview />
      <FileUpload.ItemDelete>Remove</FileUpload.ItemDelete>
    </FileUpload.Item>
  ));
}