Dropzone

InstallCopy Anchor Link

pnpm exec vegastack-design verify dropzone

pnpm dlx shadcn@4.21.0 add @vegastack/dropzone

UsageCopy Anchor Link

import { Dropzone } from "@/components/ui/dropzone";

<Dropzone
  accept={{ "image/*": [".png", ".jpg"] }}
  onFilesAccepted={(files) => stageUploads(files)}
>
  <Empty className="border">
    <EmptyHeader>
      <EmptyTitle>Drop images here</EmptyTitle>
      <EmptyDescription>or click to browse</EmptyDescription>
    </EmptyHeader>
  </Empty>
</Dropzone>;

Dropzone is acquisition only — everything behavioural lives in the use-file-drop hook (over the sanctioned react-dropzone engine), and everything after acquisition belongs to Attachment, which "owns no upload logic, only the visual state machine". The two meet at a plain File[] callback.

ScopeCopy Anchor Link

ExamplesCopy Anchor Link

Typed rejectionsCopy Anchor Link

Refusals arrive as FileDropRejection — the file plus every reason (file-too-large, file-invalid-type, too-many-files, …), aligned with the per-file state vocabulary Attachment renders.

Drag-over statesCopy Anchor Link

The surface carries the drag feedback — an inset primary stroke while a valid payload hovers, an inset destructive one when it cannot be accepted — so it works with any child, not only an Empty. An absolutely positioned border-box paints the stroke one stroke-width inside the surface, so it costs no layout and stays within WebKit's scrollable box. An Empty className="border" child can tint its dashed border in step through group-data-dragging/dropzone.

dragState paints the two states without a live DataTransfer, which neither a static example nor an automated check can synthesise. It is presentation only: a real drag always wins.

Upload queueCopy Anchor Link

Dropzone only acquires files; the host owns the queue. This example hands each accepted file to an uploadFile(file, { onProgress, signal }) call — a stub here, fetch or XMLHttpRequest in an app — and renders the queue as Attachment tiles in an AttachmentGroup layout="grid". One file and Several files switch multiple: with one, a new file replaces the last.

• In flight — AttachmentProgress and a Cancel upload action that aborts the signal and drops the file, so a cancelled single upload returns the surface to idle.
• Failed — Retry upload and Discard file. A refused file joins the queue as an error tile whose description says why ("… is larger than 25 MB.", "… isn't a supported file type."), with Discard only, since there is nothing to retry.
• Details — every file that is not yet saved gets a FieldSet, legend the file name, with a Name Input (the file name without its extension) and a Category Select, each in a Field. An empty name blocks the save with a FieldError.
• Uploaded but not saved — the save that attaches the uploads to the record is a second call. When it fails, a destructive Alert says how many files are uploaded but not saved, and the button becomes Retry save, which saves again without uploading again.

A polite status line announces each upload that finishes or fails, each cancel and discard, and the save.

FoldersCopy Anchor Link

directories turns on folder mode: a dropped folder is walked (it always is) and every accepted file comes back through onEntriesAccepted with its relativePath inside the drop — "brand/logos/mark.svg", the bare name for a loose file — so the host can recreate the folders. maxFiles then caps the whole drop: a folder with more files is refused entirely as too-many-files, never cut short. A folder picker opens from a button beside the surface through actionsRef.current.openDirectory() — never inside it, because the surface is itself the control.

const actions = React.useRef<DropzoneActions>(null);

<Dropzone directories maxFiles={500} actionsRef={actions} onEntriesAccepted={stageTree}>
  …
</Dropzone>
<Button onClick={() => actions.current?.openDirectory()}>Upload folder</Button>

API ReferenceCopy Anchor Link

Rejection shapeCopy Anchor Link

Folder entryCopy Anchor Link

ActionsCopy Anchor Link

AccessibilityCopy Anchor Link

• The accessible control is the drop surface itself — role="button", named via aria-label, tabIndex=0, with Enter/Space opening the picker through the engine's keyboard handler. The real <input type="file"> behind it is the display:none form/picker bridge, deliberately not a tab stop (an interactive control may not nest another).
• Accepted and refused batches announce through a polite live region ("Added shot.png", "2 files were refused — too large").
• The surface reflects drag state as data-dragging / data-drag-invalid (primary vs destructive border tint) — state is never colour alone: the refusal is also announced and reported through onFilesRejected.
• A missed drop never navigates the browser away — a document-level guard, scoped to file-bearing drags only (text dragged into your other inputs keeps working) and shared page-wide with ref-counting: it stays armed while any mounted Dropzone wants it, and disarms when the last one unmounts. Opt a surface out with preventWindowDrop.

Do / Don'tCopy Anchor Link