useDroppable

A React hook that creates a Droppable instance for defining drop zones.

Usage

import { useMemo } from 'react';
import { useDroppable } from 'dragdoll-react';

function DropZone() {
  const droppableSettings = useMemo(
    () => ({
      accept: (draggable) => {
        // If any of the draggable's item elements have the 'foo' class, allow
        // the draggable to be dropped.
        return !!draggable.drag?.items.some((item) => item.element.classList.contains('foo'));
      },
    }),
    [],
  );
  const [droppable, setDroppableElementRef] = useDroppable(droppableSettings);

  return (
    <div
      ref={setDroppableElementRef}
      style={{ width: '200px', height: '200px', border: '2px dashed blue' }}
    >
      Drop foo here
    </div>
  );
}

Signature

function useDroppable({
  id,
  accept,
  data,
  element,
  dndObserver,
}?: UseDroppableOptions): readonly [
  Droppable | null,
  (node: HTMLElement | SVGSVGElement | null) => void,
];

Parameters

options

Configuration settings for the Droppable instance. Extends core DroppableOptions with an optional dndObserver setting.

As per React's declarative nature, these settings are always merged with the default settings and then provided to the Droppable instance. This way there will be no cumulative effect of settings changes over time meaning that the old settings will be completely overridden by the new settings.

Treat these as live settings that can be updated dynamically without recreating the droppable (except for id, which will cause the droppable to be recreated).

id

type id = DroppableId;

The id is a unique identifier for the droppable that is assigned as the droppable's id property. It can only be provided once via the constructor options and should not be changed after instantiation.

IMPORTANT

The Droppable instance will be automatically recreated when the id setting is explicitly provided and changed.

Check the id core docs for more info.

• Optional.
• Default is a unique symbol.

accept

type accept = Set<DraggableDndGroup> | ((draggable: AnyDraggable) => boolean);

Function that determines if a draggable can be dropped on this droppable. Return true to accept, false to reject.

Check the accept core docs for more info.

• Optional.
• Default is () => true (accepts all draggables).

data

type data = { [key: string]: any };

Custom data associated with the droppable. Can be accessed during drag and drop operations.

Check the data core docs for more info.

• Optional.
• Default is {}.

element

type element = HTMLElement | SVGSVGElement;

The element to use as the drop zone. If not provided, use the returned ref callback to attach to an element.

• Optional.
• Default is undefined.

dndObserver

type dndObserver = DndObserver<any> | null;

DndObserver instance to register this droppable with. If undefined, uses the dnd observer from DndObserverContext. Set to null to explicitly opt out of any observer.

• Optional.
• Default is undefined.

Return Value

type returnValue = readonly [Droppable | null, (node: HTMLElement | SVGSVGElement | null) => void];

Returns a read-only array with two elements:

1. droppable
   • The Droppable instance, or null if not yet initialized
2. setDroppableElementRef
   • A ref callback to attach droppable to an element. This is the recommended way to attach the droppable to an element. You can alternatively provide an explicit element as the second parameter to the hook.

Types

UseDroppableSettings

// Import
import type { UseDroppableSettings } from 'dragdoll-react';

// Interface
interface UseDroppableSettings extends DroppableOptions {
  element?: HTMLElement | SVGSVGElement;
  dndObserver?: DndObserver<any> | null;
}