# Dropzone

Source: https://payloadcms.com/docs/beta/ui-components/dropzone

The `Dropzone` component adds drag, drop, and paste handling to a container. It passes the selected `FileList` to `onChange` and applies Payload's drop-target styles.

## Import

```tsx
import { Dropzone } from '@payloadcms/ui'
```

## Basic usage

**Implementation**

```tsx
const inputRef = useRef<HTMLInputElement>(null)
const [fileNames, setFileNames] = useState<string[]>([])

const selectFiles = (files: FileList) => {
  setFileNames(Array.from(files, (file) => file.name))
}

<Dropzone multipleFiles onChange={selectFiles}>
  <Button
    margin={false}
    onClick={() => inputRef.current?.click()}
  >
    Select files
  </Button>
  <input
    aria-label="Select files"
    hidden
    multiple
    onChange={(event) => event.target.files && selectFiles(event.target.files)}
    ref={inputRef}
    type="file"
  />
  <span>{fileNames.length ? fileNames.join(', ') : 'or drag and drop files here'}</span>
</Dropzone>
```

**Styling**

Override semantic surface, border, and radius tokens on Dropzone while preserving its drag-and-drop interaction states.

```css
@layer payload {
  .dropzone {
    background: var(--color-bg-secondary);
    border-color: var(--color-border);
    border-radius: var(--radius-medium);
  }
}
```

- `--color-bg-secondary`: Drop target surface.
- `--color-border`: Drop target outline.
- `--radius-medium`: Drop target corner radius.

`Dropzone` does not render a file input or open the system file picker. Render those controls as children when users should be able to browse for files in addition to dropping them.

It also has no awareness of Collections or existing documents, so controls such as **Create New** and **Choose from existing** must come from the surrounding field interface.

When `multipleFiles` is disabled, dropping more than one file passes only the first file to `onChange`.

## Common props

These are the props most commonly used with this component. See its exported types in `@payloadcms/ui` for the complete list.

| Prop            | Type                        | Default     | Description                                        |
| --------------- | --------------------------- | ----------- | -------------------------------------------------- |
| `children`      | `ReactNode`                 | —           | Content and file-selection controls in the target. |
| `onChange` \*   | `(files: FileList) => void` | —           | Runs when files are dropped, pasted, or supplied.  |
| `multipleFiles` | `boolean`                   | `false`     | Allows more than one file to be returned.          |
| `disabled`      | `boolean`                   | `false`     | Disables drag, drop, and paste listeners.          |
| `dropzoneStyle` | `'default' \| 'none'`       | `'default'` | Enables or removes Payload's drop-target styles.   |
| `className`     | `string`                    | —           | Adds a class to the dropzone container.            |

_\* An asterisk denotes that a prop is required._
