Skip to content

Drop zone

Choose files by browsing or dropping them, checked against type, size and count in words.

<div class="cap-drop" data-cap="drop-zone" data-max-bytes="5242880" data-max-files="4" data-paste id="dz-idle">
  <label class="cap-drop-label">
    <input class="cap-drop-input" type="file" multiple accept="image/*,.pdf" data-cap-part="input" aria-labelledby="dz-idle-title" aria-describedby="dz-idle-hint" />
    <span class="cap-drop-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 16V4m0 0L7 9m5-5 5 5M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /></svg></span>
    <span class="cap-drop-title" id="dz-idle-title"><span class="cap-drop-idle">Drop files here, or <span class="cap-drop-browse">browse</span></span><span class="cap-drop-over">Drop to upload</span></span>
    <span class="cap-drop-hint" id="dz-idle-hint">Images and PDF, up to 5 MB each, up to 4 at a time.</span>
  </label>
  <div class="cap-drop-status" role="status" data-cap-part="status"></div>
  <div class="cap-drop-rejections" role="alert" data-cap-part="rejections"></div>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/drop-zone.css";
import { enhance } from "capsomer/behavior/drop-zone";

enhance();

Usage

<div class="cap-drop" data-cap="drop-zone" data-max-bytes="5242880" data-max-files="4" data-paste>
  <label class="cap-drop-label">
    <input class="cap-drop-input" type="file" multiple accept="image/*,.pdf" data-cap-part="input"
           aria-labelledby="up-title" aria-describedby="up-hint" />
    <span class="cap-drop-icon" aria-hidden="true"><svg>…</svg></span>
    <span class="cap-drop-title" id="up-title">
      <span class="cap-drop-idle">Drop files here, or <span class="cap-drop-browse">browse</span></span>
      <span class="cap-drop-over">Drop to upload</span>
    </span>
    <span class="cap-drop-hint" id="up-hint">Images and PDF, up to 5 MB each, up to 4 at a time.</span>
  </label>
  <div class="cap-drop-status" role="status" data-cap-part="status"></div>
  <div class="cap-drop-rejections" role="alert" data-cap-part="rejections"></div>
</div>
import { enhance, validateFiles, acceptFiles } from "capsomer/behavior/drop-zone";
enhance(); // every [data-cap="drop-zone"]
zone.addEventListener("cap-drop-accepted", (e) => upload(e.detail.accepted));
zone.addEventListener("cap-drop-rejected", (e) => log(e.detail.rejected)); // each { file, reason: "type" | "size" | "count", message }
const { accepted, rejected } = validateFiles(files, { accept: "image/*,.pdf", maxBytes: 5 * 1024 * 1024, maxFiles: 4 }); // pure
import { DropZone } from "capsomer/react/drop-zone";
<DropZone accept="image/*,.pdf" maxBytes={5 * 1024 * 1024} maxFiles={4} multiple scope="page" paste
  hint="Images and PDF, up to 5 MB each, up to 4 at a time." onAccepted={(files) => upload(files)} />
// An app that shows its own upload queue:
<DropZone accept="image/*" multiple acceptedList={false} onAccepted={(files) => queue.add(files)} />

Examples

File over

<div class="cap-drop" data-state="over" id="dz-over">
  <label class="cap-drop-label">
    <input class="cap-drop-input" type="file" multiple accept="image/*,.pdf" data-cap-part="input" aria-labelledby="dz-over-title" aria-describedby="dz-over-hint" />
    <span class="cap-drop-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 16V4m0 0L7 9m5-5 5 5M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /></svg></span>
    <span class="cap-drop-title" id="dz-over-title"><span class="cap-drop-idle">Drop files here, or <span class="cap-drop-browse">browse</span></span><span class="cap-drop-over">Drop to upload</span></span>
    <span class="cap-drop-hint" id="dz-over-hint">Images and PDF, up to 5 MB each, up to 4 at a time.</span>
  </label>
  <div class="cap-drop-status" role="status" data-cap-part="status"></div>
  <div class="cap-drop-rejections" role="alert" data-cap-part="rejections"></div>
</div>

Files refused, each with its reason

<div class="cap-drop" data-state="rejected" id="dz-rejected">
  <label class="cap-drop-label">
    <input class="cap-drop-input" type="file" multiple accept="image/*,.pdf" data-cap-part="input" aria-labelledby="dz-rejected-title" aria-describedby="dz-rejected-hint" />
    <span class="cap-drop-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 16V4m0 0L7 9m5-5 5 5M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /></svg></span>
    <span class="cap-drop-title" id="dz-rejected-title"><span class="cap-drop-idle">Drop files here, or <span class="cap-drop-browse">browse</span></span><span class="cap-drop-over">Drop to upload</span></span>
    <span class="cap-drop-hint" id="dz-rejected-hint">Images and PDF, up to 5 MB each, up to 4 at a time.</span>
  </label>
  <div class="cap-drop-status" role="status" data-cap-part="status"></div>
  <div class="cap-drop-rejections" role="alert" data-cap-part="rejections">
    <p class="cap-drop-lead" data-tone="crit"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z" /></svg>3 files were not added</p>
    <ul class="cap-drop-files">
      <li>fieldnotes-scan.heic: type not allowed. This takes images and PDF.</li>
      <li>site-recording.pdf: too big at 8.4 MB. The limit is 5 MB.</li>
      <li>logo-variant-5.png: too many files. The limit is 4 files at a time, so this one was left out.</li>
    </ul>
  </div>
</div>

Several files taken

<div class="cap-drop" id="dz-accepted">
  <label class="cap-drop-label">
    <input class="cap-drop-input" type="file" multiple accept="image/*,.pdf" data-cap-part="input" aria-labelledby="dz-accepted-title" aria-describedby="dz-accepted-hint" />
    <span class="cap-drop-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 16V4m0 0L7 9m5-5 5 5M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /></svg></span>
    <span class="cap-drop-title" id="dz-accepted-title"><span class="cap-drop-idle">Drop files here, or <span class="cap-drop-browse">browse</span></span><span class="cap-drop-over">Drop to upload</span></span>
    <span class="cap-drop-hint" id="dz-accepted-hint">Images and PDF, up to 5 MB each, up to 4 at a time.</span>
  </label>
  <div class="cap-drop-status" role="status" data-cap-part="status">
    <p class="cap-drop-lead">3 files are ready to upload.</p>
    <ul class="cap-drop-files">
      <li><span class="cap-drop-file-name">spring-hero.jpg</span><span class="cap-drop-file-size">412 kB</span></li>
      <li><span class="cap-drop-file-name">uptime-report-september.pdf</span><span class="cap-drop-file-size">1.8 MB</span></li>
      <li><span class="cap-drop-file-name">annual-report-chart.png</span><span class="cap-drop-file-size">96 kB</span></li>
    </ul>
  </div>
  <div class="cap-drop-rejections" role="alert" data-cap-part="rejections"></div>
</div>

One file only

<div class="cap-drop" data-cap="drop-zone" data-max-bytes="1048576" id="dz-single">
  <label class="cap-drop-label">
    <input class="cap-drop-input" type="file" accept=".png,.jpg,.jpeg" data-cap-part="input" aria-labelledby="dz-single-title" aria-describedby="dz-single-hint" />
    <span class="cap-drop-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 16V4m0 0L7 9m5-5 5 5M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /></svg></span>
    <span class="cap-drop-title" id="dz-single-title"><span class="cap-drop-idle">Drop a profile picture, or <span class="cap-drop-browse">browse</span></span><span class="cap-drop-over">Drop to upload</span></span>
    <span class="cap-drop-hint" id="dz-single-hint">PNG or JPG, up to 1 MB. One file.</span>
  </label>
  <div class="cap-drop-status" role="status" data-cap-part="status"></div>
  <div class="cap-drop-rejections" role="alert" data-cap-part="rejections"></div>
</div>

The app lists the files in its own queue

<div class="cap-drop" data-cap="drop-zone" data-accepted-list="off" data-max-bytes="5242880" id="dz-own-list">
  <label class="cap-drop-label">
    <input class="cap-drop-input" type="file" multiple accept="image/*" data-cap-part="input" aria-labelledby="dz-own-list-title" aria-describedby="dz-own-list-hint" />
    <span class="cap-drop-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 16V4m0 0L7 9m5-5 5 5M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /></svg></span>
    <span class="cap-drop-title" id="dz-own-list-title"><span class="cap-drop-idle">Drop images here, or <span class="cap-drop-browse">browse</span></span><span class="cap-drop-over">Drop to upload</span></span>
    <span class="cap-drop-hint" id="dz-own-list-hint">Images up to 5 MB each. They upload at once.</span>
  </label>
  <div class="cap-drop-rejections" role="alert" data-cap-part="rejections"></div>
</div>

Disabled

<div class="cap-drop" id="dz-disabled">
  <label class="cap-drop-label">
    <input class="cap-drop-input" type="file" disabled data-cap-part="input" aria-labelledby="dz-disabled-title" aria-describedby="dz-disabled-hint" />
    <span class="cap-drop-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 16V4m0 0L7 9m5-5 5 5M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /></svg></span>
    <span class="cap-drop-title" id="dz-disabled-title"><span class="cap-drop-idle">Uploads are paused</span><span class="cap-drop-over">Drop to upload</span></span>
    <span class="cap-drop-hint" id="dz-disabled-hint">The media bucket is read-only until the migration finishes.</span>
  </label>
</div>

Drop anywhere on the page, files over the window

<main>
  <h1>Media library</h1>
  <p>Drag a file anywhere on this page. A panel covers the window and says what releasing does.</p>
  <div class="cap-drop" data-cap="drop-zone" data-scope="page" data-state="over" data-max-bytes="5242880" id="dz-page">
    <label class="cap-drop-label">
      <input class="cap-drop-input" type="file" multiple accept="image/*" data-cap-part="input" aria-labelledby="dz-page-title" aria-describedby="dz-page-hint" />
      <span class="cap-drop-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 16V4m0 0L7 9m5-5 5 5M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /></svg></span>
      <span class="cap-drop-title" id="dz-page-title"><span class="cap-drop-idle">Drop files anywhere, or <span class="cap-drop-browse">browse</span></span><span class="cap-drop-over">Drop to upload</span></span>
      <span class="cap-drop-hint" id="dz-page-hint">Images up to 5 MB each.</span>
    </label>
    <div class="cap-drop-status" role="status" data-cap-part="status"></div>
    <div class="cap-drop-rejections" role="alert" data-cap-part="rejections"></div>
    <div class="cap-drop-overlay" aria-hidden="true">
      <div>
        <p class="cap-drop-overlay-title">Drop to upload</p>
        <p class="cap-drop-overlay-text">Release anywhere on this page to add the files.</p>
      </div>
    </div>
  </div>
</main>

API reference

DropZone

PropTypeRequiredDoes
acceptstringThe same list an input's accept attribute takes: "image/*,.pdf".
maxBytesnumberThe largest file, in bytes.
maxFilesnumberThe most files taken at once. A zone without multiple takes one.
multipleboolean
namestringThe input's name, so a form posts the accepted files.
disabledboolean
scope"zone" | "page""page": a drag of files anywhere over the window is taken, with a full-window panel.
pastebooleanFiles pasted from the clipboard are taken too.
titleReactNodeThe idle title ("Drop files here, or browse" by default) and the line of rules under it.
hintReactNode
acceptedListbooleanfalse: the zone does not list the files it took ("3 files are ready to upload." and the list), because the app shows its own upload queue. Refusals are still listed.
onAccepted(files: File[], rejected: Rejection[]) => voidCalled with the files that passed, and again with the files that did not.
onRejected(rejected: Rejection[], accepted: File[]) => void
idstring

Functions

FunctionSignatureDoes
parseAccept(accept: string | null | undefined): string[]"image/*, .pdf" gives ["image/*", ".pdf"], lower-cased.
matchesAccept(file: Pick<FileLike, "name" | "type">, accept: string | null | undefined): booleanThe platform's rule for accept: an extension, a type with a wildcard, or an exact type.
acceptLabel(accept: string | null | undefined): stringThe accept list as a person would say it: "images and PDF", "JPEG, PNG and WebP".
rejectionMessage(file: FileLike, reason: RejectReason, rules: DropRules): string
validateFiles<F extends FileLike>(files: Iterable<F> | ArrayLike<F>, rules?: DropRules): Validation<F>Checks every file, in order. A file is refused for its type first, then its size; the files that pass are counted, and any beyond maxFiles are refused as too many. Nothing is dropped silently: every refusal comes back with a sentence that names the file.
acceptedText(files: readonly FileLike[]): stringThe words for what was taken: "photo.jpg is ready to upload", "3 files are ready to upload".
rejectedLead(count: number): string"1 file was not added", "3 files were not added".
dragHasFiles(e: Pick<DragEvent, "dataTransfer">): booleanTrue while the pointer carries files (and not a dragged link or a selection of text).
setInputFiles(input: HTMLInputElement, files: readonly File[]): booleanPuts files into the input, so a form posts them. Returns false where the browser cannot.
rulesOf(zone: HTMLElement): DropRulesThe rules a zone states: accept from its input, limits from its data attributes. A zone that takes one file (no multiple attribute) takes at most one.
acceptFiles(zone: HTMLElement, files: Iterable<File> | ArrayLike<File>, opts?: { fromInput?: boolean | undefined; }): Validation<File>Checks files against the zone's rules, shows the result, puts the accepted files in the input, and tells the page with cap-drop-accepted and cap-drop-rejected. Returns the result.
attachDropZone(zone: HTMLElement): () => voidAttaches one zone. Returns a function that detaches it.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="drop-zone"] under root not yet attached. Returns a function that detaches them all.

CSS variables

VariableDefault
--cap-drop-edgevar(--line-strong)

Parts and data attributes

ClassIs
.cap-dropthe root
.cap-drop-browsea part
.cap-drop-file-sizea part
.cap-drop-filesa part
.cap-drop-hinta part
.cap-drop-icona part
.cap-drop-idlea part
.cap-drop-inputa part
.cap-drop-labela part
.cap-drop-leada part
.cap-drop-overa part
.cap-drop-overlaya part
.cap-drop-overlay-texta part
.cap-drop-overlay-titlea part
.cap-drop-rejectionsa part
.cap-drop-statusa part
.cap-drop-titlea part
AttributeValues
data-accepted-listoff
data-scopepage
data-stateover rejected
data-tonecrit
StateRead from
:disabledthe platform
:emptythe platform
:focus-visiblethe platform
:hoverthe platform

Accessibility

KeyDoes
Tab, Shift TabMoves to the zone (the input) and past it; the zone is one stop
Enter, Space on the focused zoneOpens the file picker
Ctrl V, Cmd V (with data-paste)Takes files from the clipboard

Dropping is a pointer gesture; the picker is its keyboard equivalent and goes through the same check.

  • The control is a native file input. Its name is the title ("Drop files here, or browse"; "Drop to upload" while over), its description the line of rules ("Images and PDF, up to 5 MB each, up to 4 at a time.").
  • Refusals are role="alert", results role="status". The page-mode panel is aria-hidden: it repeats words the zone already carries, and a drag is not something a screen reader user does.
  • The idle edge reaches 3:1 against the page; the hint is --muted at 4.5:1 and, while over, --text on the tint.
  • Hit area: the whole zone, at least three controls high; density moves it.
  • Forced colors: the edge is CanvasText, over is Highlight, the refusal box keeps its border.
  • Reduced motion: the edge and tint change without easing.