react-dropzone

Simple React hook to create a HTML5-compliant drag'n'drop zone for files.

Documentation and examples at https://react-dropzone.js.org. Source code at https://github.com/react-dropzone/react-dropzone/.

Installation

Install it from npm. react-dropzone ships as ESM and CommonJS with TypeScript types included, and works with any modern bundler (Vite, webpack, Rspack, etc.).

npm install react-dropzone

or:

yarn add react-dropzone

Usage

You can either use the hook:

import React, {useCallback} from "react";
import {useDropzone} from "react-dropzone";

function MyDropzone() {
  const onDrop = useCallback(acceptedFiles => {
    // Do something with the files
  }, []);
  const {getRootProps, getInputProps, isDragActive} = useDropzone({onDrop});

  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      {isDragActive ? <p>Drop the files here ...</p> : <p>Drag 'n' drop some files here, or click to select files</p>}
    </div>
  );
}

Or the wrapper component for the hook:

import React from "react";
import Dropzone from "react-dropzone";

<Dropzone onDrop={acceptedFiles => console.log(acceptedFiles)}>
  {({getRootProps, getInputProps}) => (
    <section>
      <div {...getRootProps()}>
        <input {...getInputProps()} />
        <p>Drag 'n' drop some files here, or click to select files</p>
      </div>
    </section>
  )}
</Dropzone>;

If you want to access file contents you have to use the FileReader API:

import React, {useCallback} from "react";
import {useDropzone} from "react-dropzone";

function MyDropzone() {
  const onDrop = useCallback(acceptedFiles => {
    acceptedFiles.forEach(file => {
      const reader = new FileReader();

      reader.onabort = () => console.log("file reading was aborted");
      reader.onerror = () => console.log("file reading has failed");
      reader.onload = () => {
        // Do whatever you want with the file contents
        const binaryStr = reader.result;
        console.log(binaryStr);
      };
      reader.readAsArrayBuffer(file);
    });
  }, []);
  const {getRootProps, getInputProps} = useDropzone({onDrop});

  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      <p>Drag 'n' drop some files here, or click to select files</p>
    </div>
  );
}

Dropzone Props Getters

The dropzone property getters are just two functions that return objects with properties which you need to use to create the drag 'n' drop zone. The root properties can be applied to whatever element you want, whereas the input properties must be applied to an <input>:

import React from "react";
import {useDropzone} from "react-dropzone";

function MyDropzone() {
  const {getRootProps, getInputProps} = useDropzone();

  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      <p>Drag 'n' drop some files here, or click to select files</p>
    </div>
  );
}

Note that whatever other props you want to add to the element where the props from getRootProps() are set, you should always pass them through that function rather than applying them on the element itself. This is in order to avoid your props being overridden (or overriding the props returned by getRootProps()):

<div
  {...getRootProps({
    onClick: event => console.log(event),
    role: "button",
    "aria-label": "drag and drop area"
    // ...and any other props
  })}
/>

In the example above, the provided {onClick} handler will be invoked before the internal one, therefore, internal callbacks can be prevented by simply using stopPropagation. See Events for more examples.

Important: if you omit rendering an <input> and/or binding the props from getInputProps(), opening a file dialog will not be possible.

Refs

Both getRootProps and getInputProps accept a custom refKey (defaults to ref) as one of the attributes passed down in the parameter.

This can be useful when the element you're trying to apply the props from either one of those fns does not expose a reference to the element, e.g:

import React from "react";
import {useDropzone} from "react-dropzone";
// NOTE: After v4.0.0, styled components exposes a ref using forwardRef,
// therefore, no need for using innerRef as refKey
import styled from "styled-components";

const StyledDiv = styled.div`
  // Some styling here
`;
function Example() {
  const {getRootProps, getInputProps} = useDropzone();
  return (
    <StyledDiv {...getRootProps({refKey: "innerRef"})}>
      <input {...getInputProps()} />
      <p>Drag 'n' drop some files here, or click to select files</p>
    </StyledDiv>
  );
}

If you're working with Material UI v4 and would like to apply the root props on some component that does not expose a ref, use RootRef:

import React from "react";
import {useDropzone} from "react-dropzone";
import RootRef from "@material-ui/core/RootRef";

function PaperDropzone() {
  const {getRootProps, getInputProps} = useDropzone();
  const {ref, ...rootProps} = getRootProps();

  return (
    <RootRef rootRef={ref}>
      <Paper {...rootProps}>
        <input {...getInputProps()} />
        <p>Drag 'n' drop some files here, or click to select files</p>
      </Paper>
    </RootRef>
  );
}

IMPORTANT: do not set the ref prop on the elements where getRootProps()/getInputProps() props are set, instead, get the refs from the hook itself:

import React from "react";
import {useDropzone} from "react-dropzone";

function Refs() {
  const {
    getRootProps,
    getInputProps,
    rootRef, // Ref to the `<div>`
    inputRef // Ref to the `<input>`
  } = useDropzone();
  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      <p>Drag 'n' drop some files here, or click to select files</p>
    </div>
  );
}

If you're using the <Dropzone> component, though, you can set the ref prop on the component itself which will expose the {open} prop that can be used to open the file dialog programmatically:

import React, {createRef} from "react";
import Dropzone from "react-dropzone";

const dropzoneRef = createRef();

<Dropzone ref={dropzoneRef}>
  {({getRootProps, getInputProps}) => (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      <p>Drag 'n' drop some files here, or click to select files</p>
    </div>
  )}
</Dropzone>;

dropzoneRef.open();

Testing

react-dropzone makes some of its drag 'n' drop callbacks asynchronous to enable promise based getFilesFromEvent() functions. In order to test components that use this library, you need to use the react-testing-library:

import React from "react";
import Dropzone from "react-dropzone";
import {act, fireEvent, render} from "@testing-library/react";

test("invoke onDragEnter when dragenter event occurs", async () => {
  const file = new File([JSON.stringify({ping: true})], "ping.json", {type: "application/json"});
  const data = mockData([file]);
  const onDragEnter = jest.fn();

  const ui = (
    <Dropzone onDragEnter={onDragEnter}>
      {({getRootProps, getInputProps}) => (
        <div {...getRootProps()}>
          <input {...getInputProps()} />
        </div>
      )}
    </Dropzone>
  );
  const {container} = render(ui);

  await act(() => fireEvent.dragEnter(container.querySelector("div"), data));
  expect(onDragEnter).toHaveBeenCalled();
});

function mockData(files) {
  return {
    dataTransfer: {
      files,
      items: files.map(file => ({
        kind: "file",
        type: file.type,
        getAsFile: () => file
      })),
      types: ["Files"]
    }
  };
}

NOTE: using Enzyme for testing is not supported at the moment, see #2011.

More examples for this can be found in react-dropzone's own test suites.

Caveats

Required React Version

React 18 or above is required because we use hooks (the lib itself is a hook).

File Paths

Files returned by the hook or passed as arg to the onDrop cb won't have the properties path or fullPath. For more inf check this SO question and this issue.

Tauri (and other native webviews)

Inside a Tauri webview, OS file drops are intercepted by the native window layer before the webview sees them, so the browser's drag 'n' drop events never fire and the dropzone appears to ignore drops. Disable Tauri's native handling to let react-dropzone work unchanged: set dragDropEnabled: false (Tauri v2) or fileDropEnabled: false (Tauri v1) in tauri.conf.json. If you instead need the absolute paths of dropped files, keep native handling on and drive your own state from Tauri's drag-drop event. See the Using with Tauri guide and #1316.

Not a File Uploader

This lib is not a file uploader; as such, it does not process files or provide any way to make HTTP requests to some server; if you're looking for that, checkout filepond or uppy.io.

Paste to Upload

Pasting files into the dropzone is supported out of the box: when the dropzone (or a focused child, e.g. a <textarea>) has focus and the user pastes files with Ctrl/Cmd+V - for instance a screenshot copied to the clipboard - those files run through the same accept, size and validator checks and the same onDrop/onDropAccepted/onDropRejected callbacks as a drop. Pastes that carry no files (plain text and the like) are ignored and left untouched, so pasting into inputs keeps working.

The paste is only received when the dropzone has focus, so pair it with autoFocus or let the user click/tab into it first. To disable paste handling, set noPaste:

import React from "react";
import {useDropzone} from "react-dropzone";

function MyDropzone() {
  const {getRootProps, getInputProps} = useDropzone({noPaste: true});

  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      <p>Drag 'n' drop or click - pasting is disabled</p>
    </div>
  );
}

Using <label> as Root

If you use <label> as the root element, the file dialog will be opened twice; see #1107 and #1432 why. A <label> natively forwards clicks to the <input> it wraps, so the dialog opens once from that and once from our own click handler. To avoid this, use noClick:

import React, {useCallback} from "react";
import {useDropzone} from "react-dropzone";

function MyDropzone() {
  const {getRootProps, getInputProps} = useDropzone({noClick: true});

  return (
    <label {...getRootProps()}>
      <input {...getInputProps()} />
    </label>
  );
}

Using open() on Click

If you bind a click event on an inner element and use open(), it will trigger a click on the root element too, resulting in the file dialog opening twice. To prevent this, use the noClick on the root:

import React, {useCallback} from "react";
import {useDropzone} from "react-dropzone";

function MyDropzone() {
  const {getRootProps, getInputProps, open} = useDropzone({noClick: true});

  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      <button type="button" onClick={open}>
        Open
      </button>
    </div>
  );
}

Changing Props Before open()

Browsers only let you open the file dialog from within a short window after a user gesture (a "transient user activation"). Because of this, open() must run synchronously in the same event that the user triggered - it cannot wait for React to re-render.

So if you update a prop (e.g. accept) and call open() in the same handler, open() runs against the previous render, before the new prop is applied. Some browsers (notably Safari) may also drop the file dialog entirely, so it appears to require a second click. See #1188.

// 🚫 open() runs with the old `accept` - and may not open at all on Safari
function MyDropzone() {
  const [accept, setAccept] = useState({"image/*": []});
  const {getRootProps, getInputProps, open} = useDropzone({accept, noClick: true});

  const pickPdfs = () => {
    setAccept({"application/pdf": []}); // applied on the next render
    open(); // still uses {"image/*": []}
  };

  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      <button type="button" onClick={pickPdfs}>
        Pick PDFs
      </button>
    </div>
  );
}

Instead, render one dropzone per set of props (each with its own open) and call the right one, so no state change has to land before opening:

function MyDropzone() {
  const images = useDropzone({accept: {"image/*": []}, noClick: true});
  const pdfs = useDropzone({accept: {"application/pdf": []}, noClick: true});

  return (
    <div {...images.getRootProps()}>
      <input {...images.getInputProps()} />
      <input {...pdfs.getInputProps()} />
      <button type="button" onClick={images.open}>
        Pick images
      </button>
      <button type="button" onClick={pdfs.open}>
        Pick PDFs
      </button>
    </div>
  );
}

Camera Option Missing on Android

On Android 13+, Chrome and Edge open the native Android photo picker whenever a file input's accept attribute resolves to only image and/or video types (e.g. accept={{"image/*": []}}). That picker only lists the gallery and files - it has no "take a photo"/camera action - so the camera appears to be missing. See #1417.

This is browser/OS behavior, not something the lib controls, and it's unrelated to how the <input> is styled: a plain <input type="file"> with no accept (or one that also allows a non-media type) falls back to the older chooser that does include the Camera app.

If you need the camera, use the capture attribute, which you can pass straight through getInputProps():

// Camera only (no gallery/files)
<input {...getInputProps({capture: "environment"})} />

To offer both the camera and the gallery, render one dropzone per input (each with its own open) and let the user pick which one to trigger:

import React from "react";
import {useDropzone} from "react-dropzone";

function MyDropzone({onDrop}) {
  const gallery = useDropzone({accept: {"image/*": []}, noClick: true, onDrop});
  const camera = useDropzone({accept: {"image/*": []}, noClick: true, onDrop});

  return (
    <>
      <button type="button" onClick={gallery.open}>
        Choose from gallery
      </button>
      <input {...gallery.getInputProps()} />

      <button type="button" onClick={camera.open}>
        Take a photo
      </button>
      <input {...camera.getInputProps({capture: "environment"})} />
    </>
  );
}

File Dialog Cancel Callback

The onFileDialogCancel() cb is unstable in most browsers, meaning, there's a good chance of it being triggered even though you have selected files.

We rely on using a timeout of 300ms after the window is focused (the window onfocus event is triggered when the file select dialog is closed) to check if any files were selected and trigger onFileDialogCancel if none were selected.

As one can imagine, this doesn't really work if there's a lot of files or large files as by the time we trigger the check, the browser is still processing the files and no onchange events are triggered yet on the input. Check #1031 for more info.

Fortunately, there's the File System Access API, which is currently a working draft and some browsers support it (see browser compatibility), that provides a reliable way to prompt the user for file selection and capture cancellation.

Also keep in mind that the FS access API can only be used in secure contexts.

NOTE You can enable using the FS access API with the useFsAccessApi property: useDropzone({useFsAccessApi: true}).

File System Access API

When setting useFsAccessApi to true, you're switching to the File System API (see the file system access RFC).

What this essentially does is that it will use the showOpenFilePicker method to open the file picker window so that the user can select files.

In contrast, the traditional way (when the useFsAccessApi is not set to true or not specified) uses an <input type="file"> (see docs) on which a click event is triggered.

With the use of the file system access API enabled, there's a couple of caveats to keep in mind:

1. The users will not be able to select directories
2. It requires the app to run in a secure context
3. In Electron, the path may not be set (see #1249)
4. Some browsers/configurations block showOpenFilePicker() and reject with a NotAllowedError (e.g. Microsoft Edge for Business or other restrictive enterprise/security policies). When this happens we automatically fall back to the native <input> so the file dialog still opens, provided you render one via getInputProps() (see #1429)

Supported Browsers

We use browserslist config to state the browser support for this lib, so check it out on browserslist.dev.

Need image editing?

React Dropzone integrates perfectly with Pintura Image Editor, creating a modern image editing experience. Pintura supports crop aspect ratios, resizing, rotating, cropping, annotating, filtering, and much more.

Checkout the Pintura integration example.

Support

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]

Hosting

react-dropzone.js.org hosting provided by netlify.

Contribute

Checkout the organization CONTRIBUTING.md.

License

MIT