---
title: Dropzone
description: Allows users to drag-and-drop files into a container to upload or process them.
icon: upload
author:
  name: haydenbleasel
  url: https://github.com/haydenbleasel
search:
  keywords: [file upload, drag and drop]
related:
  - /files
  - /attachment
mode: wide
---

<PoweredBy
  packages={[
    { name: 'React Dropzone', url: 'https://react-dropzone.js.org/' },
    { name: 'Lucide', url: 'https://lucide.dev/' },
  ]}
/>

### Installation

```package-install
npx shadcn@latest add @redpanda/dropzone
```

<ComponentPreview name="dropzone-demo" />

## When to use

Use this decision tree to determine when to use the Dropzone component:

```mermaid
graph TD;
    A[❓ Need file upload interface?] --> B{What upload method?};
    B --> C[✅ Drag & drop files];
    B --> D[⚠️ Button click only];
    B --> E[⚠️ Programmatic upload];

    C --> F[❓ File type restrictions?];
    D --> G[⚠️ Use Input type=file instead];
    E --> H[⚠️ Use fetch/axios directly];

    F --> I[✅ Images only];
    F --> J[✅ Documents/PDFs];
    F --> K[✅ Any file type];
    F --> L[ℹ️ Multiple file types];

    I --> M[❓ Need image preview?];
    J --> N[ℹ️ Standard dropzone];
    K --> N;
    L --> N;

    M --> O[✅ Use image preview variant];
    M --> P[ℹ️ Basic image dropzone];

    O --> Q[❓ File size/count limits?];
    P --> Q;
    N --> Q;

    Q --> R[✅ Set min/max size constraints];
    Q --> S[ℹ️ No size restrictions];

    R --> T[❓ Multiple files?];
    S --> T;

    T --> U[✅ Enable multiple file selection];
    T --> V[ℹ️ Single file only];

    U --> W[❓ Display method?];
    V --> X[ℹ️ Replace on new file];

    W --> Y[✅ Table view for file management];
    W --> Z[ℹ️ Simple list display];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class C,I,J,K,O,R,U,Y recommended;
    class D,E,G,H discouraged;
    class A,B,F,M,Q,T,W decision;
    class L,N,P,S,V,X,Z neutral;
```

## Features

- Drag and drop files to upload
- Customize the empty state and content
- Intelligently handle file types, sizes, and counts
- Show file names and sizes in a human readable format
- Handle errors and reject files
- Disable the dropzone when needed
- Customize the appearance with className
- Show file previews for images
- Replace existing files by dragging new ones
- Context provider for accessing dropzone state

## Examples

### With min and max sizes

<ComponentPreview name="dropzone-min-max-demo" />

### Multiple files

<ComponentPreview name="dropzone-multiple-demo" />

### Images only

<ComponentPreview name="dropzone-images-only-demo" />

### With custom empty state

<ComponentPreview name="dropzone-custom-empty-demo" />

### Showing an image preview

<ComponentPreview name="dropzone-image-preview-demo" />

### Avatar upload

<ComponentPreview
  name="dropzone-avatar-demo"
  description="Avatar upload dropzone with preview, replace, and remove actions."
/>

### Per-file upload progress

<ComponentPreview
  name="dropzone-progress-demo"
  description="Dropzone with per-file progress bars and an overall upload counter."
/>

### Sortable gallery

<ComponentPreview
  name="dropzone-sortable-demo"
  description="Sortable gallery after upload with drag-to-reorder behaviour."
/>

## Table

This example simulates uploads locally; files stay in the browser. The table displays file icons, progress and every failure message. Retry restarts only that file, removing the selected file clears its picker summary, and Download saves the original local file contents. The table uses the standard cell grid and owned destructive retry recipe rather than custom cell padding or button colors.

<ComponentPreview name="dropzone-table-demo" />

## Props

<div className="flex flex-row gap-x-3">
  <ExternalLink href="https://www.kibo-ui.com/components/dropzone" text="Docs" />
  <ExternalLink href="https://www.kibo-ui.com/components/dropzone#props" text="API Reference" />
</div>

## Credits

- We use [Kibo UI](https://www.kibo-ui.com/components/dropzone) for the dropdown menu component and style.

## Error ownership and action layout

Dropzone displays all validation failures with filenames and associates the error with its native action. `onError` is optional; use it for notifications or telemetry, not a duplicate validation alert. Rejection notifications use an `AggregateError` with every file reason. A later accepted selection clears the built-in message. Synchronous `onDrop` failures and picker/validator errors are visible too.

Use `appearance="avatar"` for the circular avatar picker. Other upload actions use the default recipe. `className` controls the outer layout; the ref still targets the native button. The native file input remains hidden beside the button. Custom content inside the action must be phrasing-only and contain no independent controls; put separate actions outside Dropzone.