# 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

- Don't: Use it for an avatar or logo row. Use `AvatarUpload` instead.
- Don't: Render your own `<input type="file">`. The root owns one.
- Do: Show feedback from `onReject`. A rejected file is never added, while the accepted files in the same batch are.
- Do: Treat `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.
- Do: Use `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.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `File[]` |  | The selected files, when controlled. |
| `defaultValue` | `File[]` | `[]` | The selected files on mount, when uncontrolled. |
| `onValueChange` | `(files: File[]) => void` |  | Called with the full file list whenever it changes. |
| `multiple` | `boolean` | `false` | Allows more than one file. |
| `accept` | `string` |  | Native `accept` string, such as `image/*,.pdf`. Also applied to drops. |
| `maxSize` | `number` |  | Largest size in bytes for one file. |
| `onReject` | `(rejections: FileRejection[]) => void` |  | Called with each rejected file and its reason: `accept`, `size`, or `overflow` for extra files in single mode. |
| `disabled` | `boolean` | `false` | Disables the trigger, the drop zone and the picker. |
| `inputId` | `string` | `a generated id` | The hidden input `id`, so a `<label htmlFor>` opens the picker. |

### 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.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `file` | `File` |  | The 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>
  ));
}
```

## Related

- `AvatarUpload`
- [ImageCropper](/docs/primitives/image-cropper.md)
