useDragMonitor

Observe every drag on the page without being a source or a drop target.

MonitorWaiting for a drag

'use client';
import * as React from 'react';
import { Draggable } from '@base-ui/react/draggable';
import { DropTarget } from '@base-ui/react/drop-target';
import { useDragMonitor } from '@base-ui/react/use-drag-monitor';
import styles from './hero.module.css';

type ShapeId = 'circle' | 'square' | 'triangle';

const circleKind = Draggable.createKind<ShapeId>('use-drag-monitor/shape-circle');
const squareKind = Draggable.createKind<ShapeId>('use-drag-monitor/shape-square');
const triangleKind = Draggable.createKind<ShapeId>('use-drag-monitor/shape-triangle');

const SHAPES = [
  { id: 'circle', label: 'Circle', kind: circleKind },
  { id: 'square', label: 'Square', kind: squareKind },
  { id: 'triangle', label: 'Triangle', kind: triangleKind },
] as const;

type Shape = (typeof SHAPES)[number];

const SHAPE_KINDS = SHAPES.map((shape) => shape.kind);
const IDLE_MESSAGE = 'Waiting for a drag';

function ShapePiece({ shape }: { shape: Shape }) {
  return (
    <Draggable.Root
      className={styles.Piece}
      data-shape={shape.id}
      kind={shape.kind}
      payload={shape.id}
      label={shape.label}
      aria-label={shape.label}
      role="button"
      tabIndex={0}
    />
  );
}

export default function MonitorShapeSorter() {
  const [placed, setPlaced] = React.useState<ShapeId[]>([]);
  const [message, setMessage] = React.useState(IDLE_MESSAGE);

  useDragMonitor({
    accept: SHAPE_KINDS,
    onDragStart: ({ source }) => {
      setMessage(`Picked up ${source.label}`);
    },
    onDropTargetChange: ({ source, location }) => {
      const target = location.current.dropTargets[0];
      setMessage(target ? `${source.label} over ${target.label}` : `${source.label} over nothing`);
    },
    onDrop: ({ source, dropTarget }) => {
      setPlaced((current) =>
        current.includes(source.payload) ? current : [...current, source.payload],
      );
      setMessage(`Dropped ${source.label} on ${dropTarget.label}`);
    },
    onDragEnd: ({ source }, eventDetails) => {
      if (eventDetails.reason === 'outside-release') {
        setMessage(`Released ${source.label} over nothing`);
      } else if (eventDetails.reason !== 'drop') {
        setMessage(`Canceled dragging ${source.label}`);
      }
    },
  });

  function reset() {
    setPlaced([]);
    setMessage(IDLE_MESSAGE);
  }

  return (
    <div className={styles.Root}>
      <div className={styles.Actions}>
        {placed.length > 0 && (
          <button type="button" className={styles.Reset} onClick={reset}>
            Reset
          </button>
        )}
      </div>

      <div className={styles.Tray}>
        {SHAPES.map((shape) => (
          <div key={shape.id} className={styles.TraySlot}>
            {!placed.includes(shape.id) && <ShapePiece shape={shape} />}
          </div>
        ))}
      </div>

      <div className={styles.Board}>
        {SHAPES.map((shape) => {
          const isPlaced = placed.includes(shape.id);

          return (
            <DropTarget.Root
              key={shape.id}
              className={styles.Target}
              label={`${shape.label} cutout`}
              accept={shape.kind}
            >
              <span className={styles.Cutout} data-shape={shape.id} aria-hidden="true" />
              {isPlaced && <ShapePiece shape={shape} />}
            </DropTarget.Root>
          );
        })}
      </div>

      <div className={styles.Monitor} role="status">
        <span className={styles.MonitorLabel}>Monitor</span>
        <span className={styles.MonitorMessage}>{message}</span>
      </div>
    </div>
  );
}

useDragMonitor runs callbacks for every drag on the page. A monitor has no element and renders nothing. It only observes, so no provider is required.

Use it for a status bar, analytics, shared drag state, or committing an update from one place instead of each target’s onDrop. In the shape sorter above, the cutouts only declare what they accept. A monitor updates the live status and places each shape after a successful drop.

A monitor registers once for the component’s lifetime. Re-renders do not register it again, and Base UI reads the latest callbacks for every event. A monitor mounted during a drag observes the rest of that drag.

Filter by kind

accept declares which kinds a monitor observes. Pass one kind or an array. Base UI evaluates it when the monitor joins a drag, either at drag start or when a monitor mounts during a drag. If accept excludes that drag, the monitor ignores the rest of it.

Observe only cards

const card = Draggable.createKind<CardPayload>('card');

useDragMonitor({ accept: card, onDragStart: ({ source }) => announce(source.label) });

The accepted kinds determine the type of source.payload. An array produces a union that each kind’s matches method can narrow. Omit accept to observe every drag with an unknown payload. Return early from callbacks to apply more specific filters.

Drag events

A monitor’s event handlers are optional. Each receives the drag source, location history, and mode, which is either 'pointer' or 'keyboard':

Reacting to every stage of a drag

import { useDragMonitor } from '@base-ui/react/use-drag-monitor';

function DragActivity() {
  useDragMonitor({
    accept: card,
    // Fires once when a matching drag begins, wherever it started.
    onDragStart: ({ source }) => {
      console.log('picked up', source.label);
    },
    // Fires as the pointer moves, throttled to one call per animation frame.
    // Read `location.current.input` for the pointer position.
    onDrag: ({ location }) => {
      const { clientX, clientY } = location.current.input;
      console.log('moved to', clientX, clientY);
    },
    // Fires when the drop target under the drag changes. The innermost target
    // is `location.current.dropTargets[0]`.
    onDropTargetChange: ({ location }) => {
      console.log('now over', location.current.dropTargets[0]?.label ?? 'nothing');
    },
    // Fires only when a matching drag lands on a target that accepts it.
    onDrop: ({ source, dropTarget }) => {
      console.log('dropped', source.label, 'on', dropTarget.label);
    },
    // Fires once whatever the ending: a drop, a release over empty space, or a
    // cancel.
    onDragEnd: ({ source }, eventDetails) => {
      console.log('ended', source.label, eventDetails.reason);
    },
  });

  return null;
}

Every handler receives the event payload first. Its second argument, eventDetails, contains the reason and native event.

Monitors do not receive onDragEnter or onDragLeave, which belong to drop targets. onDragEnd fires whenever the drag ends. onDrop fires only after a successful drop.

Use Draggable.useActiveDrag to read the active source without event handlers. It re-renders only when a drag starts or ends. Outside React, use useDragDropManager and its registerMonitor method.

API reference

Observes every drag operation that matches accept, regardless of which element started it. Use it for status indicators, analytics, or committing a reorder on drop.

parameters^*

WithInferredAccept<
  UseDragMonitorParameters<TPayload | unknown>,
  AnyDragAccept
>

—

Name: parameters
Type: WithInferredAccept< UseDragMonitorParameters<TPayload | unknown>, AnyDragAccept >

Return value

void

useDragMonitor.ParametersHide

type useDragMonitorParameters<TSourceData = unknown> = {
  /**
   * One or more drag source kinds observed by this monitor. Omit it to observe
   * every drag with `source.payload` typed as `unknown`.
   *
   * Base UI evaluates this value when the monitor joins a drag, either at drag
   * start or when the monitor registers during a drag. If the value excludes the
   * drag, the monitor ignores its remaining events. Return early from callbacks to
   * apply more specific filters.
   */
  accept?: DragAccept<TSourceData>;
  /**
   * Event handler called when any matching drag starts (once per drag),
   * wherever it originated.
   */
  onDragStart?: (
    parameters: DragStartEvent<TSourceData>,
    eventDetails: DragStartEventDetails,
  ) => void;
  /**
   * Event handler called (rAF-throttled) as the pointer moves during any
   * matching drag.
   */
  onDrag?: (parameters: DragMoveEvent<TSourceData>, eventDetails: DragMoveEventDetails) => void;
  /**
   * Event handler called when the active drop-target stack changes during any
   * matching drag.
   */
  onDropTargetChange?: (
    parameters: DropTargetChangeEvent<TSourceData>,
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called when a matching drag is released over an accepting drop
   * target, and only then. `dropTarget` is never `null` here.
   */
  onDrop?: (
    parameters: DragDropEvent<TSourceData>,
    eventDetails: { reason: 'drop'; event: PointerEvent | KeyboardEvent },
  ) => void;
  /**
   * Event handler called once when the drag ends after a drop, outside release, or
   * cancellation. `eventDetails.reason` identifies the outcome. `dropTarget` is the
   * target of a release, or `null` when there was none.
   */
  onDragEnd?: (parameters: DragEndEvent<TSourceData>, eventDetails: DragEndEventDetails) => void;
}

useDragMonitor.ReturnValueHide

type useDragMonitorReturnValue = useDragMonitor.ReturnValue