# Drop Zone

A drag-and-drop file upload target with a click-to-browse fallback.

- Category: Forms
- Page: https://wunderui.com/components/drop-zone
- Tier: Free

## Install

```bash
npx wunderui-cli add drop-zone
```

## Import

```tsx
import { DropZone } from "@/components/wunderui/drop-zone"
```

## Minimal usage

Then use it:

```tsx
import { DropZone } from "@/components/ui/drop-zone"

export function Attachments({ upload }: { upload: (files: FileList) => void }) {
  return <DropZone accept="image/*,application/pdf" hint="Images or PDF up to 10 MB" onFiles={upload} />
}
```

Expected result: You see a dashed box with an upload icon, Drop files here or browse and a hint. A file dragged over turns the border indigo, and dropping or choosing one hands it to your code.

## Usage

```tsx
import { DropZone } from "@/components/ui/drop-zone"

export function Example({ upload }: { upload: (files: FileList) => void }) {
  return (
    <DropZone onFiles={upload} />
  )
}
```

## When to use

### Use Drop Zone for

- Uploads where drag and drop saves time, such as images, documents or an import file
- Several files at once, because the zone always accepts more than one
- A large target on an empty page or in a dialog, where a small button would be easy to miss

### Use something else

- [Button](https://wunderui.com/components/button) for a single file in a tight form row, with a button that opens the file dialog
- [Progress](https://wunderui.com/components/progress) for how far a file that is already uploading has come
- [Empty State](https://wunderui.com/components/empty-state) for a page with nothing in it yet, where the first action is not an upload

## Keyboard

The zone is a label around a native file input, so the browser provides focus and activation. Dropping files needs a pointer; the keyboard path is the file dialog.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus onto the zone and off it. The zone has one tab stop, and the indigo border and ring mark it. |
| `Enter` or `Space` | Opens the file dialog of the system. The chosen files arrive in `onFiles` like dropped ones. |
| `Escape` | In the file dialog: closes it without choosing. `onFiles` is not called. |

## Behavior

What the zone does with files, the drag, state and motion.

- **It only receives:** DropZone hands the files to your handler and does nothing else. It never uploads, previews or stores a file, and has no progress, error or disabled state of its own.
- **Drag over:** While a file is over the zone the border turns indigo and the fill a light indigo. This ends on drop and when the file leaves.
- **Always several files:** The input accepts several files, so a dialog or a drop can hand over any number in one call. Take the first one if you only want one.
- **A copy of the list:** The handler gets its own copy of the file list, so it stays valid after the input is reset or the drag ends.
- **The same file again:** The input is reset after every choice, so choosing the same file a second time calls the handler again.
- **Accept and drops:** The accept setting filters the file dialog only. A dropped file of another type still arrives in your handler, so check it there.
- **Hint:** Without a hint the line lists the accepted types or says Any file type. A hint replaces it and is the place for a size limit.
- **Motion:** The border and fill change colour on the fast duration. Nothing moves.
- **Reduced motion:** There is no movement to remove, so reduced motion changes nothing. The colour change stays.

## Anatomy

- `DropZone`: A label with a 2 px dashed border around a real file input. A drop anywhere on it, or a click, hands the files to your handler, and while a file is dragged over it the border and fill turn indigo.
- `Icon`: An upload icon in the tertiary text colour. It is decorative and hidden from assistive technology.
- `Prompt`: The line Drop files here or browse. It is the visible name of the control.
- `Browse link`: The word browse in the link colour. It is not a separate button: a click anywhere on the zone opens the file dialog.
- `Hint`: The small line under the prompt, by default the accepted types or Any file type. It is where a size limit belongs and the accessible description of the file input.
- `File input`: The real file input, visually hidden and always accepting several files. It takes the keyboard focus, and the focus ring is drawn around the whole zone.

## Best practices

### Do

- State the limit in the hint, for example PNG, JPG or PDF up to 10 MB. The zone does not enforce a size, so say what you will check.
- Show every file in a list under the zone, with name, size, a progress bar while it uploads and a Remove or Cancel action. The zone itself shows no files.
- Say in words why a file was refused, for example that the type is not supported and which types work. Keep the row so people see which file it was.
- Check the type and size of every file in your file handler. A drop passes every file, whatever the accept setting says.

### Don't

- Don't rely on accept to keep wrong files out. It only filters the file dialog, and a dropped file of any type still reaches your handler.
- Don't make drag and drop the only way in. The zone also opens the file dialog on a click and on Enter or Space, so keep that path working.
- Don't put the zone inside another clickable element, such as a button or a link. It is already a label around an input, and the click would count twice.
- Don't use it for a single file in a tight form row. A Button that opens the file dialog takes less room and reads as a form control.

## API reference

### DropZone

| Prop | Type | Default | Description |
|---|---|---|---|
| accept | string |  | The types the file dialog offers, as for `<input accept>`: `image/*`, `application/pdf` or `.csv`, separated by commas. It does not filter dropped files. It also feeds the default hint. |
| className | string |  | Extra classes for the zone, for example `p-6` for a tighter box. It does not hold the drag-over look; the zone adds that itself. |
| hint | React.ReactNode |  | The line under the prompt. Defaults to the accepted types, or `Any file type`. State your size limit here. |
| onFiles | (files: FileList) => void |  | Called with a `FileList` of the files that were dropped or chosen in the file dialog. It is a copy, so it stays valid after the call. Check type and size here. |

## Examples

### State: idle, drag over, uploading, error and success

```tsx
import { DropZone } from "@/components/ui/drop-zone"

export function Example({ upload }: { upload: (files: FileList) => void }) {
  return (
    <DropZone
      accept="image/png,image/jpeg,application/pdf"
      hint="PNG, JPG or PDF up to 10 MB"
      onFiles={upload}
    />
  )
}
```

### Hint: any file, accepted types or a size limit

```tsx
import { DropZone } from "@/components/ui/drop-zone"

export function Example({ upload }: { upload: (files: FileList) => void }) {
  return (
    <DropZone onFiles={upload} />
  )
}
```

## In context

### Attach files to a ticket

Every file is checked in the handler. Accepted files show progress and a check, refused ones say why, and the upload is only a timer, so nothing is sent.

```tsx
import { useEffect, useState } from "react"
import { CircleAlert, CircleCheck, FileText } from "lucide-react"
import { Button } from "@/components/ui/button"
import { DropZone } from "@/components/ui/drop-zone"
import { Progress } from "@/components/ui/progress"

const TYPES = ["image/png", "image/jpeg", "application/pdf"]
const MAX_BYTES = 10 * 1024 * 1024

type Row = { id: number; name: string; size: number; progress: number; error?: string }

function sizeLabel(bytes: number) {
  return bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.max(1, Math.round(bytes / 1024))} KB`
}

export function Example() {
  const [rows, setRows] = useState<Row[]>([{ id: 1, name: "brand-guidelines.pdf", size: 2516582, progress: 100 }])

  // Pretend upload: the progress climbs on a timer. A real page sends each file and reports the real progress here.
  useEffect(() => {
    if (!rows.some((row) => !row.error && row.progress < 100)) return
    const timer = setInterval(() => {
      setRows((current) =>
        current.map((row) => (row.error || row.progress >= 100 ? row : { ...row, progress: Math.min(100, row.progress + 12) }))
      )
    }, 300)
    return () => clearInterval(timer)
  }, [rows])

  // The zone passes every dropped file, so the type and the size are checked here.
  function add(files: FileList) {
    const next = Array.from(files).map((file, index) => ({
      id: Date.now() + index,
      name: file.name,
      size: file.size,
      progress: 0,
      error: !TYPES.includes(file.type)
        ? "File type not supported. Use PNG, JPG or PDF."
        : file.size > MAX_BYTES
          ? "File is larger than 10 MB."
          : undefined,
    }))
    setRows((current) => [...current, ...next])
  }

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <DropZone accept="image/png,image/jpeg,application/pdf" hint="PNG, JPG or PDF up to 10 MB" onFiles={add} />
      <ul className="flex max-h-56 min-h-32 flex-col gap-2 overflow-y-auto">
        {rows.map((row) => (
          <li
            key={row.id}
            className={`flex items-center gap-3 rounded-xl border bg-card p-2 ${row.error ? "border-tint-red" : "border-border"}`}
          >
            <span
              className={`flex size-10 shrink-0 items-center justify-center rounded-md ${
                row.error ? "bg-tint-red text-tint-text-red" : row.progress >= 100 ? "bg-tint-green text-tint-text-green" : "bg-tint-indigo text-tint-text-indigo"
              }`}
            >
              {row.error ? <CircleAlert className="size-5" aria-hidden /> : row.progress >= 100 ? <CircleCheck className="size-5" aria-hidden /> : <FileText className="size-5" aria-hidden />}
            </span>
            <div className="min-w-0 flex-1">
              <p className="truncate text-sm font-medium text-foreground">{row.name}</p>
              {row.error ? (
                <p role="alert" className="text-xs text-tint-text-red">{row.error}</p>
              ) : row.progress >= 100 ? (
                <p className="text-xs text-text-secondary">{sizeLabel(row.size)} · Uploaded</p>
              ) : (
                <>
                  <p className="text-xs text-text-secondary">{sizeLabel(row.size)} · {row.progress}% uploaded</p>
                  <Progress value={row.progress} aria-label={`Uploading ${row.name}`} className="mt-1" />
                </>
              )}
            </div>
            <Button variant="plain" size="sm" onClick={() => setRows((current) => current.filter((item) => item.id !== row.id))}>
              {!row.error && row.progress < 100 ? "Cancel" : "Remove"}
            </Button>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Import contacts from a CSV

One file counts, and a file of another kind is refused in words under the zone. The Import button waits until a CSV is chosen.

```tsx
import { useState } from "react"
import { FileSpreadsheet } from "lucide-react"
import { Button } from "@/components/ui/button"
import { DropZone } from "@/components/ui/drop-zone"

export function Example() {
  const [file, setFile] = useState<File | null>(null)
  const [error, setError] = useState<string | null>(null)

  // Only the first file counts here, and a drop passes every file whatever `accept` says.
  function choose(files: FileList) {
    const first = files[0]
    if (!first.name.toLowerCase().endsWith(".csv")) {
      setFile(null)
      setError("That is not a CSV file. Choose a .csv export.")
      return
    }
    setError(null)
    setFile(first)
  }

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <DropZone accept=".csv" hint="CSV up to 5 MB" onFiles={choose} />
      <p role="alert" className="min-h-5 text-xs text-tint-text-red">
        {error}
      </p>
      {file ? (
        <div className="flex items-center gap-3 rounded-xl border border-border bg-card p-2">
          <span className="flex size-10 shrink-0 items-center justify-center rounded-md bg-tint-green text-tint-text-green">
            <FileSpreadsheet className="size-5" aria-hidden />
          </span>
          <p className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">{file.name}</p>
          <Button variant="plain" size="sm" onClick={() => setFile(null)}>
            Remove
          </Button>
        </div>
      ) : (
        <div className="flex h-14 items-center justify-center rounded-xl border border-dashed border-border text-xs text-text-tertiary">No file chosen</div>
      )}
      <Button variant="gradient" disabled={!file}>
        Import contacts
      </Button>
    </div>
  )
}
```

## For AI agents

`get_component("drop-zone")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
