<!--
Source: https://www.theui.dev/docs/file-dropzone
Part of the theui-svelte documentation. Index: https://www.theui.dev/llms.txt
-->

# File Dropzone

The FileDropzone component takes files by drag and drop or by clicking to browse. It checks the type, the size and the number of files, shows what was chosen with image previews, and lets each file be removed again. Underneath it is a real file input, so it submits with the form and works from the keyboard.

## Example

Import the component and bind `files`. Drop a file on the box, or click it to open the file browser.

```html
<script>
  import { FileDropzone } from "theui-svelte";
  let files = $state<FileList>()
</script>

<FileDropzone bind:files>Attachment</FileDropzone>
```

## Multiple Files

Add `multiple` to accept more than one file, and `maxFiles` to set a ceiling. New files are added to the ones already chosen, so a second drop does not throw the first away.

```html
<FileDropzone multiple maxFiles={4} text="Drop up to four files" />
```

## Type and Size

Use `accept` exactly as on a file input, with extensions such as `.pdf` or types such as `image/*`, and `maxSize` in bytes. Files that do not pass are handed to `onreject`, each with the reason: `type`, `size` or `count`.

These checks run in the browser, where anyone can work around them, and the type comes from the file name and what the browser reports. They are there to spare your visitors a pointless upload, not to keep bad files out. Check the type, the size and the number of files again on your server before you store anything.

```html
<FileDropzone
  accept=".pdf,.doc,.docx"
  maxSize={2 * 1024 * 1024}
  hint="PDF or Word, up to 2 MB"
  onreject={(rejections) => {
    // [{ file, reason: "type" | "size" | "count" }]
    console.log(rejections)
  }}
>Resume</FileDropzone>
```

## Image Previews

Images are shown as thumbnails in the list below the box. Set `preview={false}` to list the names only, or `showList={false}` to hide the list and show the files yourself.

```html
<FileDropzone multiple accept="image/*" text="Drop a few pictures" hint="Images only" />

<!-- Names only -->
<FileDropzone multiple preview={false} />

<!-- No list at all -->
<FileDropzone multiple showList={false} bind:files />
```

## Text and Hint

The `text` prop is the line inside the box and `hint` is the smaller line under it. Use the hint to say what is allowed, so the rule is known before a file is picked.

```html
<FileDropzone
  text="Drag your logo here, or click to browse"
  hint="SVG or PNG, at most 500 KB"
  accept=".svg,.png"
  maxSize={500 * 1024}
/>
```

## Custom Content

The `content` snippet replaces everything inside the box, so you can use your own icon and wording.

```html
<FileDropzone multiple dropzoneClasses="py-10">
  {#snippet content()}
    <Svg size={2} class="text-brand-500">
      <path d="..."/>
    </Svg>
    <span class="font-semibold">Drop your files</span>
    <span class="text-sm text-muted">or click anywhere in this box</span>
  {/snippet}
</FileDropzone>
```

## Reacting to Files

The `onselect` callback runs with the files that were accepted, which is the place to start an upload. Everything that was turned away goes to `onreject` instead.

```html
<FileDropzone
  multiple
  onselect={(files) => upload(files)}
  onreject={(rejections) => showErrors(rejections)}
>Upload</FileDropzone>
```

## Disabled

A `disabled` dropzone takes nothing, by drop or by click, and its list loses the remove buttons.

```html
<FileDropzone disabled text="Uploading is off right now" />
```

## Sizes

The `size` prop sets how tall the drop area is and how large the text inside it reads. It takes `"sm"`, `"md"`, `"lg"` and `"xl"`, and the default is `"md"`. Inside a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) the value is inherited.

```html
<FileDropzone size="sm" text="Small" />
<FileDropzone size="md" text="Medium" />
<FileDropzone size="lg" text="Large" />
<FileDropzone size="xl" text="Extra large" />
```

## Reset Styles

Set `reset` to `true` to drop the dashed border, the hover and the drag highlight and keep only the classes you pass in `dropzoneClasses`. The drop area keeps its layout and its size, so dropping, clicking and the file list all still work. The default is `false`, and a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) can set it for every field it holds.

```html
<FileDropzone
  reset
  dropzoneClasses="rounded-xl bg-secondary shadow-sm"
  text="Drop a file here" />
```

## Customization

Use `dropzoneClasses` for the box, `listClasses` for the list of chosen files and `wrapperClasses` for the whole field.

```html
<FileDropzone dropzoneClasses="border-brand-500 bg-brand-500/5" text="Brand coloured" />
<FileDropzone dropzoneClasses="border-solid border-2 py-10" rounded="2xl" text="Solid border" />
```

## Accessibility

Drag and drop is never the only way in: the box is a label tied to a real file input, so Tab reaches it, Enter and Space open the file browser, and the same focus ring appears as on any other field. The list of chosen files is a plain list with a named remove button for each file, such as "Remove report.pdf", and each row shows the file size in readable units. Say what is allowed in the `hint` or `helperText`, and report what was turned away in your own text through `onreject`, so the reason is not carried by colour alone.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `files` | FileList | `undefined` | The chosen files. Bindable with `bind:files`. |
| `multiple` | boolean | `false` | Accepts more than one file. New files are added to the ones already chosen. |
| `accept` | string | `undefined` | Allowed file types, such as ".pdf,.docx" or "image/*". Anything else is rejected with the reason "type". |
| `maxSize` | number | `undefined` | Largest size of one file, in bytes. A bigger file is rejected with the reason "size". |
| `maxFiles` | number | `undefined` | How many files may be kept. Files over the limit are rejected with the reason "count". |
| `preview` | boolean | `true` | Shows a thumbnail of every image in the list. |
| `showList` | boolean | `true` | Shows the list of chosen files with their size and a remove button. |
| `text` | string | `Drop files here or click to browse` | Main line inside the box. |
| `hint` | string | `undefined` | Smaller line under the main text, for the rules such as allowed types and size. |
| `onselect` | (files: File[]) => void | `undefined` | Runs with the files that were accepted. |
| `onreject` | (rejections: [DROPZONE_REJECTION](https://www.theui.dev/docs/types#dropzone-rejection-type)[]) => void | `undefined` | Runs with the files that were turned away, each with its reason: "type", "size" or "count". |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form, or "md` | Sets the size of the component. |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the box and the list rows. |
| `helperText` | string \| Snippet | `undefined` | Text under the field, linked to the input for screen readers. |
| `labelClasses` | string | `` | Custom classes for the label. |
| `wrapperClasses` | string | `` | Custom classes for the field wrapper. |
| `dropzoneClasses` | string | `` | Custom classes for the drop box. |
| `listClasses` | string | `` | Custom classes for the list of chosen files. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes passed to the file input. |
| `disabled` | Turns the dropzone off, for dropping and for clicking. |
| `name` | Name of the field, so the files are submitted with the form. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label of the field. |
| `content` | Replaces the icon and text inside the drop box. |

---

Category: Forms
Keywords: file dropzone, upload, drag and drop, file input, form, svelte, svelte-5, theui-svelte, component-library, ui, tailwindcss
Full documentation set: https://www.theui.dev/llms-full.txt
