Drop Zone
FreeA target for files: drop them on it or click it to choose them. It hands the files to your code and never uploads anything itself.
npx wunderui-cli add drop-zonePlayground
Installation
npx wunderui-cli add drop-zoneWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { DropZone } from "@/components/wunderui/drop-zone"Then use it:
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.
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 for
- Button for a single file in a tight form row, with a button that opens the file dialog
- Progress for how far a file that is already uploading has come
- Empty State for a page with nothing in it yet, where the first action is not an upload
State
The zone has two looks: waiting, and indigo while a file is dragged over it. What happens after the drop is yours to show, usually a row per file with progress, an error or a check.
report-q3.pdf
2.4 MB · 62% uploaded
x
report-q3.pdf
Upload failed. Check your connection and try again.
report-q3.pdf
2.4 MB · Uploaded
Hint
The line under the prompt says what the zone takes. It lists the accepted types or your own hint text, such as a size limit, but neither is enforced for dropped files, so check them in your handler.
Keyboard interactions
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.
- TaborShift+Tab
- Moves focus onto the zone and off it. The zone has one tab stop, and the indigo border and ring mark it.
- EnterorSpace
- Opens the file dialog of the system. The chosen files arrive in like dropped ones.
- Escape
- In the file dialog: closes it without choosing. is not called.
Behavior and motion
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
The figure shows the zone, its icon, the prompt with the browse link and the hint. The hidden file input inside the zone has no mark.
- 1
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.
- 2
An upload icon in the tertiary text colour. It is decorative and hidden from assistive technology.
- 3
The line Drop files here or browse. It is the visible name of the control.
- 4
The word browse in the link colour. It is not a separate button: a click anywhere on the zone opens the file dialog.
- 5Optional
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.
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.
- Do
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.
- Do
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.
- Do
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
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
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
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 is one component with four props, and the table lists every one. It renders a label and passes no other attributes on.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| onFiles | (files) => void | — | Called with a 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. |
| accept | string | — | The types the file dialog offers, as for : , or , separated by commas. It does not filter dropped files. It also feeds the default hint. |
| hint | ReactNode | — | The line under the prompt. Defaults to the accepted types, or . State your size limit here. |
| className | string | — | Extra classes for the zone, for example for a tighter box. It does not hold the drag-over look; the zone adds that itself. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("drop-zone")npx wunderui-cli add drop-zoneThe full library index for assistants is at /llms.txt.