react-dropzone

react-dropzone is a small, dependency-light React hook (useDropzone) that turns any element into an HTML5-compliant drag-and-drop file upload zone. It handles the native drag/drop and file-picker plumbing — accepted/rejected file lists, MIME-type and extension filtering, size limits, multi-file support, and keyboard accessibility — and exposes prop-getter functions (getRootProps, getInputProps) so consumers can style the drop target however they like without fighting the library’s DOM.

It has been the de-facto standard for file uploads in the React ecosystem for years, with over 10,000 apps depending on it in production. The library ships as ESM and CommonJS with first-class TypeScript types, has zero runtime dependencies beyond two small internal packages (attr-accept, file-selector), and works with any modern bundler.

What You Get

• A useDropzone hook that returns getRootProps()/getInputProps() prop-getter functions to wire drag-and-drop and click-to-browse onto any element you render
• Built-in file validation: accept (MIME type/extension filtering), minSize/maxSize, maxFiles, and a pluggable validator function for custom rules
• Granular drag-state booleans (isDragActive, isDragAccept, isDragReject, isDragUnknown, isFocused) for building responsive visual feedback
• Keyboard and focus accessibility out of the box, including noKeyboard/noClick/noDrag escape hatches for custom interaction models
• First-class TypeScript types and an optional File System Access API mode (useFsAccessApi) for richer native file pickers where supported

Common Use Cases

• Adding a drag-and-drop upload zone to a form that then hands accepted files off to your own upload/HTTP logic
• Building an image or media uploader with client-side type/size validation before hitting an API
• Multi-file batch upload UIs (e.g. document management, CMS asset panels) with per-file rejection reasons surfaced to the user
• Accessible file-picker components where both drag-and-drop and keyboard/click flows must work identically

Under The Hood

Architecture The useDropzone hook holds all interaction state in a single useReducer (isFocused, isDragActive/Accept/Reject/Unknown, acceptedFiles, fileRejections). Drag/drop event handlers call getFilesFromEvent (defaulting to file-selector’s fromEvent) to normalize native DataTransfer/FileList/FileSystemFileHandle inputs into a Promise<File[]>, then validate each file via fileAccepted/fileMatchSize/a custom validator before splitting results into acceptedFiles vs fileRejections and firing onDrop/onDropAccepted/onDropRejected. Root-scoped drag handlers compute a local accept/reject verdict via getDragVerdict, while separate document-level dragenter/dragleave/dragend/drop listeners (attached once via useEffect) track a global drag flag and prevent the browser’s default “open file in new tab” behavior for drops that land outside the configured zone. getRootProps/getInputProps are composeEventHandlers-based prop-getters that merge caller-supplied handlers with internal ones without clobbering either, and forwardRef exposes an imperative open() to trigger the hidden <input type="file"> programmatically.

Tech Stack TypeScript source (src/index.tsx ~840 lines, src/utils/index.ts ~430 lines) is bundled with tsdown into dual ESM/CJS output plus generated .d.ts types. Runtime dependencies are minimal — just attr-accept (MIME/extension matching) and file-selector (normalizing native file events) — with react >=18 as a peer dependency and @types/react optional. The dev toolchain is modern: oxlint/oxfmt for lint/format, Vitest + @testing-library/react + jsdom for tests, vocs for the documentation site, and semantic-release wired for automated npm/GitHub releases from conventional commits.

Code Quality The test suite (src/index.spec.tsx) runs to roughly 4,000 lines, covering drag/drop/paste event simulation, keyboard interaction, validator edge cases, and File System Access API branches, backed by snapshot tests; src/utils/index.spec.ts separately unit-tests the pure helper functions. Code is consistently typed with explicit interfaces (DropzoneOptions, DropzoneState, FileRejection, Accept, FileError) rather than loose any usage, and inline comments document non-obvious browser-compatibility workarounds with links to the originating GitHub issues. The pretest:cov script gates coverage runs behind type-check, lint, and format-check, indicating quality gates are enforced in CI rather than left informal.

API Design Returning prop-getter functions instead of pre-rendered markup is a deliberate, well-executed tradeoff: it costs a small amount of boilerplate ({...getRootProps()} / {...getInputProps()}) in exchange for consumers keeping full control over DOM structure and styling, and the getters correctly compose caller-supplied event handlers with internal ones instead of silently overwriting them. Defaults are sensible enough that a bare useDropzone({onDrop}) call produces a working zone, and escape hatches (noClick, noKeyboard, noDrag, noDragEventsBubbling) are provided for documented edge cases (e.g. <label> double-opening the file dialog) rather than leaving consumers to work around them unaided. Documentation is strong throughout — the README covers installation, both hook and wrapper-component usage, refs, testing patterns, and a dedicated “Caveats” section enumerating known browser quirks.