React Basic Dropzone

React Basic Dropzone is React library for files uploading via drag&drop or by click in a dropzone area.

Read more about React Basic Dropzone:

• Features
• Installation
• Usage
• Demo
• Compatibility
• Licence

Features

• Drag & drop + click to select
• MIME type validation (accept prop)
• File size & count limits
• Upload progress tracking
• Upload cancellation (AbortController)
• Keyboard accessible (ARIA)
• Tree-shakeable (ES + CJS)
• Full TypeScript support

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:

Run the following to use the latest stable version

npm install --save react-basic-dropzone

Peer dependencies: react >= 18.0.0 and react-dom >= 18.0.0

Tailwind CSS Requirement

This component uses Tailwind CSS utility classes. Make sure your Tailwind config scans the library:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/react-basic-dropzone/dist/**/*.js', // ← add this
  ],
}

Usage

import { Dropzone, DropzoneProps, UploadCbProps } from 'react-basic-dropzone'
import axios from 'axios'
import { AxiosError, AxiosProgressEvent } from 'axios'

const upload: UploadCbProps = async (file, setUploadResult, setProgressValue, controllerRef) => {

    if(controllerRef && controllerRef.current){
        controllerRef.current.abort();
    }
    
    if(controllerRef){
        controllerRef.current = new AbortController();
    }

    try{
        setUploadResult("uploading")

        const api = axios.create({
            baseURL: `/api`,
            timeout: 35000,
        })

        const endpoint = 'files/upload'

        const body: FormData = new FormData()
        body.append('files', file)

        const apiReq = await api.post(endpoint, body, {
            signal: controllerRef?.current?.signal,
            onUploadProgress: (event: AxiosProgressEvent) => {
                if(event.total && setProgressValue) {
                    const current: number = Math.round((event.loaded / event.total) * 100) || 0
                    setProgressValue(current)
                }
            }
        })


        if(controllerRef) controllerRef.current = null;

        if(apiReq){
            setProgressValue && setProgressValue(100)
            setUploadResult("success")
        }
        else {
            setUploadResult("error")
        }
    }
    catch(err: unknown){
        if(controllerRef) controllerRef.current = null;
        if((err instanceof DOMException && err.name === 'AbortError') || (err instanceof Error && err.message === 'canceled')) {
            setUploadResult("canceled")
        }
        else setUploadResult("error")
    }
}

function App(){
    return (
        <div className="w-lg mx-auto">
            <Dropzone 
                upload={upload} 
                maxFiles={5} 
                maxFileSize={5 * 1024 * 1024 * 1024} 
                accept={'image/*'}
                disabled={false}
            />
        </div>
    )
}

API Reference

<Dropzone /> Props

Prop	Type	Required	Default	Description
upload	UploadCbProps	✅	—	Upload callback function (see below)
maxFiles	number	✅	—	Maximum number of files allowed
maxFileSize	number	✅	—	Maximum file size in bytes
disabled	boolean	✅	—	Disables the dropzone
accept	string	—	'*/*'	Accepted MIME types. Supports wildcards: 'image/*', comma-separated: 'image/png, application/pdf'
textContent	TextContent	—	see below	Customize UI text

textContent

{
  title?: string       // Default: "Drag and drop files here or click to select"
  description?: string // Default: "Max file size: {formatted}"
}

UploadCbProps

The upload callback receives the following parameters:

type UploadCbProps = (
  file: File,
  setUploadResult: (value: 'idle' | 'uploading' | 'success' | 'error' | 'canceled') => void,
  setProgressValue?: (value: number) => void,
  controllerRef?: RefObject<AbortController | null>
) => Promise<void> | void

Parameter	Type	Description
file	File	The file to upload
setUploadResult	function	Set upload status: 'idle', 'uploading', 'success', 'error', 'canceled'
setProgressValue	function	Set progress percentage (0–100)
controllerRef	RefObject	AbortController ref for cancellation

useDropzone(options) Hook

For custom UI implementations, use the hook directly:

import { useDropzone } from 'react-basic-dropzone'
const {
  processedFiles,   // FileWithId[] — accepted files
  processFiles,     // (files: File[], accept?: string) => void
  setProcessedFiles,// (files: FileWithId[]) => void
  removeFile,       // (id: string) => void
  clearFiles,       // () => void
  errors,           // string[] — error codes
  rejectedFiles,    // string[] — rejected file names
} = useDropzone({
  maxFiles: 10,
  maxFileSize: 5 * 1024 * 1024,
})

Options

Option	Type	Required	Description
maxFiles	number	✅	Maximum files allowed
maxFileSize	number	✅	Maximum file size in bytes

Error Codes

Code	Description
'invalid_file_type'	File MIME type doesn't match accept
'max_files_count'	Maximum file count exceeded
'big_file_size'	File exceeds maxFileSize

FileWithId Type

type FileWithId = {
  id: string       // Unique identifier (crypto.randomUUID)
  uploaded: boolean // true after successful upload
  file: File       // Native File object
}

formatSize(bytes: number): string

Utility to format bytes into human-readable string:

import { formatSize } from 'react-basic-dropzone'
formatSize(1536)      // "1.5 KB"
formatSize(5242880)   // "5 MB"
formatSize(0)         // "0 B"

Compatibility

The library is compatible with the Chrome 92+, Firefox 95+, Safari 15.4+, Edge 92+. IE is not supported.

Unfortunately, it is difficult to support legacy browsers while maintaining our ability to develop new features in the future. For IE9 support, it is known that the classlist polyfill is needed, but this may change or break at any point in the future.

Demo

Here is the link to the demo website

License

MIT