DropZone
An area that takes files dropped on it, pasted or opened with a shortcut, and says so while a file is held over it.
import { DropZone } from "@butteryui/react";Demo
Add a background
Drag a picture onto the slide, paste it from your clipboard, or open one with ⌘O.
When to use it
Use it for
- Adding images or documents to a canvas or a list
- Around an EmptyState that asks for a file
Not for
- A single file field in a form: use a labelled file input
Examples
Attachments
A deck's attachments: PDFs or pictures dropped or pasted onto the list join it, each with a button to remove it.
q3-handout.pdf
q3-chart.png
Drop PDFs or pictures here, or paste them.
Background drop
An empty slide that takes a picture for its background: dropped, pasted, opened with ⌘O or picked with the button.
Add a background
Drag a picture onto the slide, or paste it from your clipboard.
Paused uploads
A drop zone that takes no files while it's disabled, here while uploads are switched off.
No picture yet
Variants and states
Picture drop
Hold a file over it to see the tint and dashed edge; only images reach onFiles.
Add a background
Drag a picture onto the slide, paste it from your clipboard, or open one with ⌘O.
Props
DropZone
| Prop | Type | Default | Description |
|---|---|---|---|
onFilesrequired | (files: readonly File[]) => void | Called with the files dropped, pasted or picked that match accept. | |
accept | string | The kinds of file it takes, as for an input, such as "image/*" or ".png,.jpg". Defaults to any. | |
multiple | boolean | false | Whether the file picker takes several files. Defaults to false. |
paste | boolean | true | Whether files pasted anywhere in the window land here, unless typing in a field. Defaults to true. |
openShortcut | Shortcut | false | "mod+o" | The shortcut that opens the file picker, or false for none. Defaults to "mod+o". |
disabled | boolean | Takes no files while set. | |
labels | Partial<DropZoneLabels> | Words to use instead of the English ones. |
It also takes ComponentPropsWithRef<"div">.
DropZone.Open
| Prop | Type | Default | Description |
|---|---|---|---|
childrenrequired | ReactElement | The control that opens the file picker, such as a "Pick a picture" button. |
DropZoneLabels
The words a `DropZone` shows, for other languages.
| Field | Type | Default | Description |
|---|---|---|---|
droprequired | string | Shown while a file is held over it. |
Also exported
| Export | Description |
|---|---|
fileMatches(file: File, accept: string | undefined): boolean | Whether a file is one of the kinds accept lists. |
Accessibility
Dropping isn't the only way in: DropZone.Open makes a button open the file picker, ⌘O opens it from anywhere, and ⌘V pastes files unless you're typing in a field. The hint shown while a file is held over it is visual only.
| Keys | What they do |
|---|---|
| ⌘O (Ctrl O) | Opens the file picker from anywhere, unless openShortcut is false or it's disabled |
| ⌘V (Ctrl V) | Adds the files on the clipboard, unless you're typing in a field or paste is false |
| Enter or Space | Opens the file picker from the button inside DropZone.Open |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It takes the size its container gives it and centers what's inside. While a file is held over it, it tints and draws a 2px dashed edge 16px inside its own, around the hint, without moving anything; the whole area takes drops, and DropZone.Open's button is the target for the picker.