Elements

useDropZone

Turns any element into a file drop zone. Tracks drag-over state and validates file types before accepting drops.

Demo

Drop Zone

Drag image files (PNG, JPEG, GIF, WebP) into the zone below.

Drag image files here

Usage

Basic drop zone

Hook
Scope

import { 
const useRef$: {
    <T = any>(initialValue: null): Ref$<T | null>;
    <T = any>(initialValue: T): Ref$<T>;
    <T = any>(): Ref$<T | null>;
}
useRef$ } from "@usels/core";
import { 
function useDropZone(target: MaybeEventTarget, options?: DeepMaybeObservable<UseDropZoneOptions> | UseDropZoneOptions["onDrop"]): UseDropZoneReturn
Turns any element into a file drop zone. Tracks drag-over state and validates
file types before accepting drops.
Accepts either an options object (supports DeepMaybeObservable) or a plain
onDrop callback shorthand.
useDropZone } from "@usels/web";

function 
function MyDropZone(): JSX.Element
MyDropZone() {
  const 
const el$: Ref$<HTMLDivElement | null>
el$ = 
useRef$<HTMLDivElement>(): Ref$<HTMLDivElement | null> (+2 overloads)
Core (framework-agnostic) version of useRef$.
Creates an observable element ref with opaque wrapping.

non-null value → Ref$<T>: current, get(), peek() return T
null / no arg → Ref$<T | null>: current, get(), peek() return T | null

Nullability is expressed via the type parameter, mirroring T | null at the call site.
useRef$<
interface HTMLDivElement
HTMLDivElement>();
  const { 
const files$: any
files$, 
const isOverDropZone$: any
isOverDropZone$ } = 
function useDropZone(target: MaybeEventTarget, options?: DeepMaybeObservable<UseDropZoneOptions> | UseDropZoneOptions["onDrop"]): UseDropZoneReturn
Turns any element into a file drop zone. Tracks drag-over state and validates
file types before accepting drops.
Accepts either an options object (supports DeepMaybeObservable) or a plain
onDrop callback shorthand.
useDropZone(
const el$: Ref$<HTMLDivElement | null>
el$, {
    
onDrop: (files: any) => any
onDrop: (
files: any
files) => 
any
console.
any
log(
files: any
files),
  });

  return (
    <
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div 
RefAttributes<HTMLDivElement>.ref?: Ref<HTMLDivElement> | undefined
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
@see ― https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs
ref={
const el$: Ref$<HTMLDivElement | null>
el$} 
HTMLAttributes<HTMLDivElement>.style?: CSSProperties | undefined
style={{ 
StandardShorthandProperties<string | number, string & {}>.background?: Property.Background<string | number> | undefined
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Syntax: <bg-layer>#? , <final-bg-layer>
| Chrome | Firefox | Safari |  Edge  |  IE   |
| :----: | :-----: | :----: | :----: | :---: |
| 1  |  1  | 1  | 12 | 4 |
@see ― https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/background
background: 
const isOverDropZone$: any
isOverDropZone$.
any
get() ? "#e0e7ff" : "#f9fafb" }}>
      Drop files here
    </
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>
  );
}

import { createRef$ } from "@usels/core";
import { createDropZone } from "@usels/web";

function MyDropZone() {
  "use scope";
  const el$ = createRef$<HTMLDivElement>();
  const { files$, isOverDropZone$ } = createDropZone(el$, {
    onDrop: (files) => console.log(files),
  });

  return (
    <div ref={el$} style={{ background: isOverDropZone$.get() ? "#e0e7ff" : "#f9fafb" }}>
      Drop files here
    </div>
  );
}

Filter by file type

// @noErrors
import { useRef$ } from "@usels/core";
import { useDropZone } from "@usels/web";

function ImageDropZone() {
  const el$ = useRef$<HTMLDivElement>();
  const { files$ } = useDropZone(el$, {
    dataTypes: ["image/png", "image/jpeg", "image/webp"],
  });
  // ...
}

Custom validation

const { files$ } = useDropZone(el$, {
  checkValidity: (items) => Array.from(items).every((item) => item.type.startsWith("image/")),
});

Single file only

const { files$ } = useDropZone(el$, {
  multiple: false,
  onDrop: (files) => files && uploadFile(files[0]),
});

Shorthand (onDrop only)

const { files$ } = useDropZone(el$, (files, event) => {
  if (files) processFiles(files);
});

Type

Parameters

Parameter	Type	Description
`target`	`MaybeEventTarget`	-
`options`	`UseDropZoneOptions` (optional)	-

UseDropZoneOptions

Option	Type	Default	Description
`dataTypes`	`string[] \| ((types: readonly string[]) => boolean)`	`-`	-
`checkValidity`	`((items: DataTransferItemList) => boolean)`	`-`	-
`onDrop`	`((files: File[] \| null, event: DragEvent) => void)`	`-`	-
`onEnter`	`((files: File[] \| null, event: DragEvent) => void)`	`-`	-
`onLeave`	`((files: File[] \| null, event: DragEvent) => void)`	`-`	-
`onOver`	`((files: File[] \| null, event: DragEvent) => void)`	`-`	-
`multiple`	`boolean`	`-`	-
`preventDefaultForUnhandled`	`boolean`	`-`	-

Returns

UseDropZoneReturn

Name	Type	Description
`files$`	`Observable<File[] \| null>`	-
`isOverDropZone$`	`ObservableBoolean<boolean>`	-

Source

View on GitHub