DropZone

API reference for the DropZone component

A comprehensive file upload component with drag-and-drop, validation, and upload progress tracking.

Import

import { DropZone } from "@zayne-labs/ui-react/ui/drop-zone";

Component Parts

DropZone.Root · component

Root provider with file upload state management

DropZone.Container · component

Drop zone container with drag-and-drop handlers

DropZone.Input · component

Hidden file input element

DropZone.Area · component

Combined container and input with context rendering

DropZone.Trigger · component

Button to open file picker

DropZone.FileList · component

Container for uploaded files

DropZone.FileItem · component

Individual file list item

DropZone.FileItemPreview · component

File preview (image or icon)

DropZone.FileItemMetadata · component

File name and size display

DropZone.FileItemProgress · component

Upload progress indicator

DropZone.FileItemDelete · component

Button to remove a file

DropZone.FileClear · component

Button to clear all files

DropZone.Context · component

Context consumer for accessing store state

DropZone.Root

Root provider that manages file upload state and validation.

Props

children · React.ReactNode · required

Child components

disabled · boolean

Whether the drop zone is disabled

multiple · boolean

Whether to allow multiple files to be uploaded

initialFiles · FileMeta | FileMeta[] | null

Initial files to populate the drop zone

disableFilePickerOpenOnAreaClick · boolean · default: false

Whether clicking the drop zone area will open the default file picker

disableInternalStateSubscription · boolean · default: false

Whether to disable the internal state subscription for data attributes. Useful if you want to subscribe to state yourself

disablePreviewGenForNonImageFiles · boolean · default: true

Whether to disallow preview generation for non-image files

unstyled · boolean

Set to true to disable the default styling

Validation Props

accept · string | string[]

Accepted file types (MIME types or extensions)

maxFiles · number

Maximum number of files allowed

maxFileSize · number

Maximum file size in bytes

minFileSize · number

Minimum file size in bytes

validator · function

Custom validation function

(file: File) => Promise<boolean> | boolean

If the function returns false, the file will be rejected

Callback Props

onFilesChange · function

Callback fired when the internal files state changes

(context: { fileStateArray: FileState[] }) => void

onUpload · function

Callback fired when new files are uploaded

(context: {
  fileStateArray: FileState[];
  onProgress: (ctx: { fileStateOrID: FileState | string; progress: number }) => void;
  onSuccess: (ctx: { fileStateOrID: FileState | string }) => void;
  onError: (ctx: { fileStateOrID: FileState | string; error: DropZoneError }) => void;
}) => Promise<void> | void

onValidationError · function

Callback fired on each file validation error

(context: FileValidationErrorContextEach) => void

onValidationSuccess · function

Callback fired after all files have been successfully validated

(context: { files: File[] }) => void

DropZone.Container

Drop zone container with drag-and-drop event handlers.

Props

as · React.ElementType · default: "div"

The element type to render as

asChild · boolean

Merge props with immediate child element

className · string

CSS class names to apply

unstyled · boolean

Disable default styling

Data Attributes

• data-scope="drop-zone"
• data-part="container"
• data-drag-over - Present when dragging over
• data-invalid - Present when validation fails

DropZone.Input

Hidden file input element.

Props

asChild · boolean

Merge props with immediate child element

className · string

CSS class names to apply

Data Attributes

• data-scope="drop-zone"
• data-part="input"
• data-drag-over - Present when dragging over

DropZone.Area

Convenience component combining Container and Input with context rendering.

Props

children · React.ReactNode | RenderFn

Child components or render function receiving store state

selector · function

State selector function

(state: DropZoneStore) => TSlice

className · string

CSS class names for container

classNames · object

Class names for parts

• container?: string
• input?: string

extraProps · object

Additional props for parts

• container?: object
• input?: object

unstyled · boolean

Disable default styling

DropZone.Trigger

Button to open the file picker.

Props

asChild · boolean

Merge props with immediate child element

className · string

CSS class names to apply

Data Attributes

• data-scope="drop-zone"
• data-part="trigger"

DropZone.FileList

Container for uploaded files with conditional rendering.

Props

as · React.ElementType · default: "ul"

The element type to render as

asChild · boolean

Merge props with immediate child element

forceMount · boolean · default: false

Force mount even when no files are present

renderMode · 'per-item' | 'manual-list' · default: "per-item"

Rendering strategy

• per-item - Render function called for each file
• manual-list - Render function receives full array

children · React.ReactNode | RenderFn

Child components or render function

Per-item mode:

(context: {
  fileState: FileState;
  index: number;
  array: FileState[];
  actions: DropZoneActions["actions"];
}) => React.ReactNode

Manual-list mode:

(context: {
  fileStateArray: FileState[];
  actions: DropZoneActions["actions"];
}) => React.ReactNode

orientation · 'horizontal' | 'vertical'

List orientation for default styling

unstyled · boolean

Disable default styling

Data Attributes

• data-scope="drop-zone"
• data-part="file-list"
• data-state="active" | "inactive"

DropZone.FileItem

Individual file list item with file state context.

Props

as · React.ElementType · default: "li"

The element type to render as

asChild · boolean

Merge props with immediate child element

fileState · FileState · required

File state object for this item

className · string

CSS class names to apply

unstyled · boolean

Disable default styling

Data Attributes

• data-scope="drop-zone"
• data-part="file-item"

DropZone.FileItemPreview

File preview component with automatic icon/image rendering.

Props

as · React.ElementType · default: "span"

The element type to render as

asChild · boolean

Merge props with immediate child element

fileState · FileState

File state object (optional if used within FileItem)

renderPreview · boolean | RenderPreviewObject | RenderPreviewFn · default: true

Preview rendering configuration

• false - Disable preview
• true - Use default preview
• Object or function for custom rendering

children · React.ReactNode | RenderFn

Custom preview content or render function

(context: {
  fileState: FileState;
  fileType: string;
  fileExtension: string;
  fallbackPreview: () => React.ReactNode;
}) => React.ReactNode

unstyled · boolean

Disable default styling

Data Attributes

• data-scope="drop-zone"
• data-part="file-item-preview"

DropZone.FileItemMetadata

File name and size display.

Props

asChild · boolean

Merge props with immediate child element

fileState · FileState

File state object (optional if used within FileItem)

size · 'default' | 'sm' · default: "default"

Text size variant

classNames · object

Class names for metadata parts

• name?: string - File name classes
• size?: string - File size classes

children · React.ReactNode | RenderFn

Custom metadata content or render function

(context: { fileState: FileState }) => React.ReactNode

unstyled · boolean

Disable default styling

Data Attributes

• data-scope="drop-zone"
• data-part="file-item-metadata"

DropZone.FileItemProgress

Upload progress indicator with multiple variants.

Props

as · React.ElementType · default: "span"

The element type to render as

asChild · boolean

Merge props with immediate child element

variant · 'linear' | 'circular' | 'fill' · default: "linear"

Progress indicator style

• linear - Horizontal progress bar
• circular - Circular progress ring
• fill - Fill overlay effect

size · number · default: 40

Size in pixels (circular variant only)

forceMount · boolean · default: false

Force mount even when progress is 100%

unstyled · boolean

Disable default styling

Data Attributes

• data-scope="drop-zone"
• data-part="file-item-progress"

DropZone.FileItemDelete

Button to remove a file from the list.

Props

asChild · boolean

Merge props with immediate child element

fileStateOrID · FileState | File | string

File to delete (optional if used within FileItem)

className · string

CSS class names to apply

Data Attributes

• data-scope="drop-zone"
• data-part="file-item-delete"

DropZone.FileClear

Button to clear all files.

Props

asChild · boolean

Merge props with immediate child element

forceMount · boolean · default: false

Force mount even when no files are present

className · string

CSS class names to apply

Data Attributes

• data-scope="drop-zone"
• data-part="file-item-clear"

DropZone.Context

Context consumer for accessing drop zone state.

Props

children · React.ReactNode | RenderFn · required

Child components or render function

(context: DropZoneStore | TSlice) => React.ReactNode

selector · function

State selector function

(state: DropZoneStore) => TSlice

Types

FileState

interface FileState {
  id: string;
  file: File | FileMeta;
  preview: string | undefined;
  progress: number;
  status: "idle" | "uploading" | "success" | "error";
  error?: FileErrorContext;
}

DropZoneStore

type DropZoneStore = DropZoneState & DropZoneActions;

type DropZoneState = {
  fileStateArray: FileState[];
  errors: FileErrorContext[];
  isDraggingOver: boolean;
  isInvalid: boolean;
};

type DropZoneActions = {
  actions: {
    addFiles: (files: FileList | File[] | null) => Promise<void> | void;
    clearErrors: () => void;
    clearFiles: () => void;
    clearObjectURLs: () => void;
    handleChange: (event: React.ChangeEvent<HTMLInputElement>) => Promise<void> | void;
    handleDragEnter: (event: React.DragEvent<HTMLElement>) => void;
    handleDragLeave: (event: React.DragEvent<HTMLElement>) => void;
    handleDragOver: (event: React.DragEvent<HTMLElement>) => void;
    handleDrop: (event: React.DragEvent<HTMLElement>) => Promise<void> | void;
    handleFileUpload: (ctx: { newFileStateArray: FileState[] }) => Promise<void> | void;
    handleKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
    handlePaste: (event: React.ClipboardEvent<HTMLElement>) => Promise<void> | void;
    openFilePicker: () => void;
    removeFile: (ctx: { fileStateOrID: FileState | File | string }) => void;
    setInputRef: (element: HTMLInputElement | null) => void;
    updateFileState: (ctx: { fileStateOrID: FileState | File | string; } & Partial<Omit<FileState, "file" | "id" | "preview">>) => void;
  };
};

UseDropZoneResult

interface UseDropZoneResult {
  inputRef: React.RefObject<HTMLInputElement | null>;
  propGetters: DropZonePropGetters;
  storeApi: ReturnType<typeof createDropZoneStore>;
  useDropZoneStore: typeof useDropZoneStoreContext;
  disabled: boolean;
  disableInternalStateSubscription: boolean;
}

Hooks

useDropZone

import { useDropZone } from "@zayne-labs/ui-react/ui/drop-zone";

const result = useDropZone({
  multiple: true,
  maxFiles: 5,
  onUpload: async ({ fileStateArray, onProgress, onSuccess }) => {
    // Handle upload
  },
});

useDropZoneStoreContext

import { useDropZoneStoreContext } from "@zayne-labs/ui-react/ui/drop-zone";

function CustomComponent() {
  const fileCount = useDropZoneStoreContext((state) => state.fileStateArray.length);
  const { clearFiles } = useDropZoneStoreContext((state) => state.actions);
  
  return <div>Files: {fileCount}</div>;
}