Dropzone

A drop target primitive for drag-and-drop and click-to-select file selection.

Drop files here

or click to open the file picker

No files selected yet.

'use client';

import * as React from 'react';
import { Dropzone } from '@base-ui/react/dropzone';
import styles from './index.module.css';

export default function ExampleDropzone() {
  const [files, setFiles] = React.useState<File[]>([]);

  const appendFiles = React.useCallback((nextFiles: File[]) => {
    setFiles((prev) => [...prev, ...nextFiles]);
  }, []);

  return (
    <div className={styles.container}>
      <Dropzone.Root
        className={styles.dropzone}
        onFilesDrop={(droppedFiles) => appendFiles(droppedFiles)}
      >
        <Dropzone.HiddenInput
          multiple
          onChange={(event) => {
            const selected = Array.from(event.currentTarget.files ?? []);
            if (selected.length > 0) {
              appendFiles(selected);
            }
            event.currentTarget.value = '';
          }}
        />
        <p className={styles.heading}>Drop files here</p>
        <p className={styles.hint}>or click to open the file picker</p>
      </Dropzone.Root>

      {files.length === 0 ? (
        <p className={styles.empty}>No files selected yet.</p>
      ) : (
        <ul className={styles.list}>
          {files.map((file, index) => (
            <li className={styles.item} key={`${file.name}-${file.size}-${index}`}>
              {file.name}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Usage guidelines

Form controls must have an accessible name: Provide visible text in the dropzone, or set aria-label/aria-labelledby for icon-only UIs. See Labeling a dropzone and the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

import { Dropzone } from '@base-ui/react/dropzone';

<Dropzone.Root>
  <Dropzone.HiddenInput />
  Drop files here
</Dropzone.Root>

Examples

Labeling a dropzone

For icon-only designs, provide an explicit accessible name:

Icon-only dropzone

import { Dropzone } from '@base-ui/react/dropzone';

<Dropzone.Root aria-label="Upload files">
  <Dropzone.HiddenInput />
  <UploadIcon aria-hidden />
</Dropzone.Root>

API reference

Root

Interactive drop target and file selection area. Renders a <div> element.

nativeButtonbooleanfalse

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
Type: boolean | undefined
Default: false

onDraggingChangefunction—

Name: onDraggingChange
Description: Event handler called when the dragging state changes.
Type: ((dragging: boolean) => void) | undefined

onFilesDropfunction—

Name: onFilesDrop
Description: Event handler called when files are dropped onto the dropzone.
Type: | (( files: File[], event: React.DragEvent<HTMLDivElement>, ) => void) | undefined

onOpenfunction—

Name: onOpen
Description: Event handler called when the dropzone is activated without a Dropzone.HiddenInput present. Use this to open a custom file picker when the built-in hidden input is not used.
Type: (() => void) | undefined

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

children

| React.ReactNode 
|  ((state: { isDragging: boolean }) => React.ReactNode)

—

Name: children
Description: The content of the dropzone. A render function can be used to access the dragging state.
Type: | React.ReactNode | ((state: { isDragging: boolean }) => React.ReactNode) | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Dropzone.Root.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Dropzone.Root.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Dropzone.Root.State, ) => ReactElement) | undefined

data-dragging

Present when files are being dragged over the dropzone.

data-disabled

Present when the dropzone is disabled.

Attribute	Description	-
`data-dragging`	Present when files are being dragged over the dropzone.
`data-disabled`	Present when the dropzone is disabled.

Dropzone.Root.PropsHide

Re-Export of Root props as DropzoneRootProps

Dropzone.Root.StateHide

type DropzoneRootState = {
  /** Whether files are being dragged over the dropzone. */
  dragging: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
}

HiddenInput

Hidden file input that enables file selection via the native file picker. Renders an <input> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: Dropzone.HiddenInput.State, ) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Dropzone.HiddenInput.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Dropzone.HiddenInput.State, ) => ReactElement) | undefined

Dropzone.HiddenInput.PropsHide

Re-Export of HiddenInput props as DropzoneHiddenInputProps

Dropzone.HiddenInput.StateHide

type DropzoneHiddenInputState = {
  /** Whether the parent dropzone should ignore user interaction. */
  disabled: boolean;
}