# FileUpload

Drop, paste or browse for files; see them listed with previews, sizes, errors and progress.

```ehtml Example
import { FileUpload } from "@elements/ui/file-upload";

<FileUpload files={form.photos} accept="image/*" maxFiles={5} maxFileSize={5_000_000} />
<FileUpload files={form.resume} accept={[".pdf", ".docx"]} name="resume" required />
```

## Parts

| Part | What it is |
|---|---|
| `.file-upload` | The root. |
| `.file-upload-dropzone` | The drop target. |
| `.file-upload-trigger` | The Browse button. |
| `.file-upload-input` | The real file input, visually hidden. |
| `.file-upload-list` | Accepted or rejected rows. |
| `.file-upload-item` | A file row. |
| `.file-upload-item-preview` | Thumbnail or kind icon. |
| `.file-upload-item-delete` | Removes the row. |
| `.file-upload-item-progress` | The upload bar. |
| `.file-upload-clear` | Removes every file. |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `files` | `File[]` (two-way) | `[]` | Accepted files, as Elements Files with their bytes: pass them to an @rpc. Files already in the array on load are listed and in the input. |
| `rejected` | `FileRejection[]` (two-way) | `[]` | Files the last pick refused, with error codes. |
| `accept` | `string \| string[] \| Record<string, string[]>` | `""` | Allowed types: MIME, type/\*, or extensions. |
| `maxFiles` | `number` | `1` | Most files. 1 replaces the file on each pick. |
| `maxFileSize` | `number` | `Infinity` | Largest file in bytes. |
| `minFileSize` | `number` | `0` | Smallest file in bytes. |
| `directory` | `boolean` | `false` | Pick a whole folder. |
| `capture` | `"" \| "user" \| "environment"` | `""` | On phones, open the front or back camera. |
| `allowDrop` | `boolean` | `true` | Files can be dropped on the dropzone. |
| `allowPaste` | `boolean` | `true` | Files pasted while focus is inside are added. |
| `preventDocumentDrop` | `boolean` | `true` | A drop that misses the dropzone does not open the file in the tab. |
| `disableClick` | `boolean` | `false` | Clicking the dropzone does not open the picker. |
| `trigger` | `boolean` | `true` | Shows the Browse button; without it the dropzone is the button. |
| `preview` | `boolean` | `true` | Shows image thumbnails. |
| `hint` | `string` | `""` | A line under the title: allowed types and sizes. |
| `progress` | `Record<string, number>` | `{}` | Upload percent by file name; draws a bar and announces when done. |
| `locale` | `string` | `""` | Locale for file sizes. |
| `name` | `string` | `""` | The input's name; FormData carries the files. |
| `form` | `string` | `""` | The id of the form the files belong to. |
| `disabled` | `boolean` | `false` | Not interactive. |
| `readonly` | `boolean` | `false` | Shows files; nothing adds or removes them. |
| `required` | `boolean` | `false` | The form will not submit without a file. |
| `invalid` | `boolean` | `false` | Marks the field invalid. |
| `validate` | `(file, details) => FileError[] \| null` | `null` | Return error codes to refuse a file. |
| `transformFiles` | `(files) => Promise<File[]>` | `null` | Change files before they are read: resize, rename, convert. |
| `translations` | `Partial<FileUploadTranslations>` | `{}` | Text, labels and error messages. |
| `class` | `string` | `""` | Extra classes on the root. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Attributes for the file input: id, aria-label, data-\*. |
| `onFileAccept` | `(details: { files: File[] }) => void` | `() => {}` | Files accepted by a pick, drop or paste. |
| `onFileReject` | `(details: { files: FileRejection[] }) => void` | `() => {}` | Files refused, with codes. |
| `onFileChange` | `(details: { acceptedFiles, rejectedFiles }) => void` | `() => {}` | After any change. |

## Slots

| Slot | Content |
|---|---|
| `dropzone` | The dropzone's content. Default: an upload icon and a title. |
| `trigger` | The Browse button's label. |

## Keyboard

| Keys | Action |
|---|---|
| `Tab` | Moves to the Browse button, each delete button and clear. |
| `Enter / Space` | On Browse (or the dropzone without one): opens the file picker. |
| `Ctrl/Cmd + V` | Pastes files while focus is inside. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-dragging` | present while files are dragged over | root, dropzone |
| `data-reading` | present while files are read | root |
| `data-invalid` | present when invalid or a file was refused | root, dropzone, trigger |
| `data-max-reached` | present at maxFiles | root |
| `data-disabled` | present when disabled | root, dropzone, trigger, list, item, item name, size and preview |
| `data-readonly` | present when read-only | root, dropzone, trigger |
| `data-type` | `"accepted" \| "rejected"` | list, item, item name, size, preview, delete |
| `data-kind` | `"image" \| "video" \| "pdf" \| "file"` | item |
| `data-errors` | the error codes | rejected item |

## Accessibility

- A real file input holds the files, so a Field label, required and form submission work natively; Browse points at it.
- Without a Browse button the dropzone itself is a button that opens the picker with Enter or Space.
- Added, refused and removed files and finished uploads are announced; progress bars are progressbars with a value.
- After a delete, focus moves to the next delete button so it is never lost.

## See also

- [Slider](slider): Pick a value or a range by dragging thumbs along a track, with full keyboard support.
- [NumberInput](number-input): A number field with stepper buttons, keyboard steps, formatting, wheel and scrub.
- [PasswordInput](password-input): A password field with a button that shows and hides what was typed.
- [InputOTP](input-otp): A one-time code in separate slots, with paste, SMS autofill and a pattern.
- [TagsInput](tags-input): Type a list of tags into one field: add, edit, delete and paste them from the keyboard.
- [ColorPicker](color-picker): Pick a color with an area, channel sliders, inputs, swatches and the eye dropper.