Draggable

A component that makes its element a drag source.

Drag me

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

const cardKind = Draggable.createKind('card');
const CARD_WIDTH = 128;
const CARD_HEIGHT = 40;

export default function DraggableHero() {
  const surfaceRef = React.useRef<HTMLDivElement | null>(null);
  const [position, setPosition] = React.useState({ x: 24, y: 24 });

  return (
    <div className={styles.Root}>
      {/* The surface is the drop target, so a release on it reaches `onDrop`. */}
      <DropTarget.Root
        ref={surfaceRef}
        label="Canvas"
        accept={cardKind}
        trackDragOver={false}
        className={styles.Surface}
        onDrop={({ self }) => {
          const surface = surfaceRef.current;
          if (!surface) {
            return;
          }

          // No snap steps are declared, so this is the exact source-anchored point.
          const point = self.getSnappedLocalPoint({ anchor: 'source' });
          const surfaceRect = surface.getBoundingClientRect();
          setPosition({
            x: point.x * surfaceRect.width - surface.clientLeft,
            y: point.y * surfaceRect.height - surface.clientTop,
          });
        }}
      >
        <Draggable.Root
          label="Drag me"
          kind={cardKind}
          modifiers={Draggable.restrictToElement(surfaceRef)}
          role="button"
          className={styles.Card}
          style={{ left: position.x, top: position.y, width: CARD_WIDTH, height: CARD_HEIGHT }}
        >
          Drag me
          <Draggable.ClonedPreview />
        </Draggable.Root>
      </DropTarget.Root>
    </div>
  );
}

Draggable makes an element draggable with the pointer or keyboard. It pairs with DropTarget, which defines where a drag can be released. See the drag and drop overview for examples and the styling guide for drag states.

Anatomy

Import the component and assemble its parts:

Anatomy

import { Draggable } from '@base-ui/react/draggable';

const itemKind = Draggable.createKind('item');

<Draggable.Root kind={itemKind} label="Item">
  <Draggable.Handle />
  <Draggable.Displacement />
</Draggable.Root>

A root takes at most one preview part. Omit it to use a sanitized clone of the source, render Draggable.ClonedPreview to configure that clone, or use Draggable.Preview to render custom content. Declaring both warns in development; the last one mounted wins. Draggable.Displacement is independent and opts the root into reorder animations.

Pass data along

Every draggable is of a kind, declared once with Draggable.createKind and passed to both sides of the drag. Drop targets list the kinds they take in their accept, and the payload type the kind was created with is what a drop handler receives as source.payload:

Declaring a kind and a payload

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

<Draggable.Root kind={card} label={title} payload={{ id }} />

A kind with a payload type makes payload required, so a target is never handed undefined where the kind promised data. Skip the type argument for an item that is only a marker, and payload becomes optional:

An item with no data

const divider = Draggable.createKind('divider');

<Draggable.Root kind={divider} label="Divider" />

Pass getPayload instead when the payload depends on the gesture, such as where inside the element the pointer grabbed. It runs once, at drag start. payload itself is always data, so function-valued payloads are preserved without a wrapper.

Deriving the payload from the gesture

const grabbedCard = Draggable.createKind<{ id: string; grabOffsetX: number }>('card');

<Draggable.Root
  kind={grabbedCard}
  label={title}
  getPayload={({ input, element }) => {
    const rect = element.getBoundingClientRect();
    return { id, grabOffsetX: input.clientX - rect.left };
  }}
/>

Drag handle

By default, the whole element is draggable. Render a Draggable.Handle inside the root to start drags from a handle while the rest of the card stays interactive. If a draggable has several handles, only the first starts the drag.

When the root has a label and the handle renders no text, the handle uses Drag {label} as its accessible name. A handle with visible text keeps that text as its accessible name. This lets speech-input users activate it by saying the words they see. If the handle needs a longer name, add an aria-label that starts with the visible text. Base UI cannot detect visible text returned by a render function or custom component. Add an explicit aria-label or aria-labelledby when such a handle contains only an icon.

Dragging by a handle

<Draggable.Root kind={card} label={label} payload={{ id }}>
  <Draggable.Handle>
    <Grip />
  </Draggable.Handle>
  {label}
</Draggable.Root>

Visitors

2,420Last 7 days

Conversion

3.8%Up 0.4%

Drop widget

index.tsx handle.module.css

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

type SlotId = 'left' | 'center' | 'right';

interface WidgetData {
  id: string;
  title: string;
  value: string;
  detail: string;
  slot: SlotId;
}

const widgetKind = Draggable.createKind<string>('draggable/handle-widget');

const SLOTS: { id: SlotId; label: string }[] = [
  { id: 'left', label: 'Left dashboard slot' },
  { id: 'center', label: 'Center dashboard slot' },
  { id: 'right', label: 'Right dashboard slot' },
];

const INITIAL_WIDGETS: WidgetData[] = [
  {
    id: 'visitors',
    title: 'Visitors',
    value: '2,420',
    detail: 'Last 7 days',
    slot: 'left',
  },
  {
    id: 'conversion',
    title: 'Conversion',
    value: '3.8%',
    detail: 'Up 0.4%',
    slot: 'center',
  },
];

function Grip() {
  return (
    <svg className={styles.Grip} width="8" height="14" viewBox="0 0 8 14" aria-hidden="true">
      <g fill="currentColor">
        <circle cx="2" cy="2" r="1.2" />
        <circle cx="6" cy="2" r="1.2" />
        <circle cx="2" cy="7" r="1.2" />
        <circle cx="6" cy="7" r="1.2" />
        <circle cx="2" cy="12" r="1.2" />
        <circle cx="6" cy="12" r="1.2" />
      </g>
    </svg>
  );
}

function Widget({ widget }: { widget: WidgetData }) {
  return (
    <Draggable.Root
      label={`${widget.title} widget`}
      kind={widgetKind}
      payload={widget.id}
      className={styles.Widget}
    >
      <div className={styles.WidgetHeader}>
        <Draggable.Handle className={styles.Handle}>
          <Grip />
        </Draggable.Handle>
        <span>{widget.title}</span>
      </div>
      <div className={styles.WidgetBody}>
        <strong>{widget.value}</strong>
        <span>{widget.detail}</span>
      </div>
    </Draggable.Root>
  );
}

function DockSlot({
  id,
  label,
  widget,
  onMoveWidget,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
}) {
  return (
    <DropTarget.Root
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      label={label}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? <Widget widget={widget} /> : <span className={styles.Empty}>Drop widget</span>}
    </DropTarget.Root>
  );
}

export default function HandleDashboard() {
  const [widgets, setWidgets] = React.useState<WidgetData[]>(INITIAL_WIDGETS);

  function moveWidget(widgetId: string, slot: SlotId) {
    setWidgets((currentWidgets) =>
      currentWidgets.map((widget) => (widget.id === widgetId ? { ...widget, slot } : widget)),
    );
  }

  return (
    <div className={styles.Root}>
      <div className={styles.Grid}>
        {SLOTS.map((slot) => (
          <DockSlot
            key={slot.id}
            id={slot.id}
            label={slot.label}
            widget={widgets.find((widget) => widget.slot === slot.id)}
            onMoveWidget={moveWidget}
          />
        ))}
      </div>
    </div>
  );
}

Keyboard-only handle

Use Draggable.KeyboardHandle when the whole source should remain draggable with the pointer, but keyboard dragging should start only from a dedicated button. Space and Enter pick the source up while this button has focus. Activating the button with assistive technology starts the same keyboard drag.

The root stays out of the tab order while the keyboard handle is mounted. Pointer dragging still starts anywhere on the root, including over the handle.

Keeping pointer pickup on the whole card

<Draggable.Root kind={card} label={label} payload={{ id }}>
  <Draggable.KeyboardHandle>
    <Grip />
  </Draggable.KeyboardHandle>
  {label}
</Draggable.Root>

Conditional drag

Pass disabled to stop an item from being picked up with the pointer or keyboard. Clicks and context-menu presses keep their normal behavior, and screen readers no longer receive keyboard-drag instructions. You can change the prop at runtime without re-registering the draggable.

Visitors

2,420Last 7 days

Conversion

3.8%Pinned widget

Drop widget

index.tsx conditional.module.css

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

type SlotId = 'left' | 'center' | 'right';

interface WidgetData {
  id: string;
  title: string;
  value: string;
  detail: string;
  slot: SlotId;
  locked?: boolean;
}

const widgetKind = Draggable.createKind<string>('draggable/conditional-widget');

const SLOTS: { id: SlotId; label: string }[] = [
  { id: 'left', label: 'Left dashboard slot' },
  { id: 'center', label: 'Center dashboard slot' },
  { id: 'right', label: 'Right dashboard slot' },
];

const INITIAL_WIDGETS: WidgetData[] = [
  {
    id: 'visitors',
    title: 'Visitors',
    value: '2,420',
    detail: 'Last 7 days',
    slot: 'left',
  },
  {
    id: 'conversion',
    title: 'Conversion',
    value: '3.8%',
    detail: 'Pinned widget',
    slot: 'center',
    locked: true,
  },
];

function Grip() {
  return (
    <svg className={styles.Icon} width="8" height="14" viewBox="0 0 8 14" aria-hidden="true">
      <g fill="currentColor">
        <circle cx="2" cy="2" r="1.2" />
        <circle cx="6" cy="2" r="1.2" />
        <circle cx="2" cy="7" r="1.2" />
        <circle cx="6" cy="7" r="1.2" />
        <circle cx="2" cy="12" r="1.2" />
        <circle cx="6" cy="12" r="1.2" />
      </g>
    </svg>
  );
}

function Lock() {
  return (
    <svg
      className={styles.Icon}
      width="11"
      height="14"
      viewBox="0 0 11 14"
      role="img"
      aria-label="Locked"
    >
      <path d="M3 6V4.25a2.5 2.5 0 0 1 5 0V6" fill="none" stroke="currentColor" strokeWidth="1.2" />
      <rect x="1.5" y="6" width="8" height="6.5" rx="1.3" fill="currentColor" />
    </svg>
  );
}

function Widget({ widget }: { widget: WidgetData }) {
  return (
    <Draggable.Root
      label={`${widget.title} widget`}
      kind={widgetKind}
      payload={widget.id}
      disabled={widget.locked}
      role={widget.locked ? undefined : 'button'}
      className={styles.Widget}
      data-locked={widget.locked || undefined}
    >
      <div className={styles.WidgetHeader}>
        {widget.locked ? <Lock /> : <Grip />}
        <span>{widget.title}</span>
      </div>
      <div className={styles.WidgetBody}>
        <strong>{widget.value}</strong>
        <span>{widget.detail}</span>
      </div>
    </Draggable.Root>
  );
}

function DockSlot({
  id,
  label,
  widget,
  onMoveWidget,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
}) {
  return (
    <DropTarget.Root
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      label={label}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? <Widget widget={widget} /> : <span className={styles.Empty}>Drop widget</span>}
    </DropTarget.Root>
  );
}

export default function ConditionalDashboard() {
  const [widgets, setWidgets] = React.useState<WidgetData[]>(INITIAL_WIDGETS);

  function moveWidget(widgetId: string, slot: SlotId) {
    setWidgets((currentWidgets) =>
      currentWidgets.map((widget) => (widget.id === widgetId ? { ...widget, slot } : widget)),
    );
  }

  return (
    <div className={styles.Root}>
      <div className={styles.Grid}>
        {SLOTS.map((slot) => (
          <DockSlot
            key={slot.id}
            id={slot.id}
            label={slot.label}
            widget={widgets.find((widget) => widget.slot === slot.id)}
            onMoveWidget={moveWidget}
          />
        ))}
      </div>
    </div>
  );
}

When the decision needs the gesture itself, such as which handle was pressed or whether a modifier key is down, use onBeforeDragStart instead. It fires once the drag is about to start, before anything lifts, and calling eventDetails.cancel() prevents it:

Canceling a drag as it starts

<Draggable.Root
  kind={card}
  label={label}
  payload={{ id }}
  onBeforeDragStart={({ input }, eventDetails) => {
    if (input.altKey) {
      eventDetails.cancel();
    }
  }}
/>

Drag events

The optional event handlers below fire in order. All except onBeforeDragStart receive the drag source, location history, and mode, which is either 'pointer' or 'keyboard'.

Following a source through its drag

<Draggable.Root
  kind={card}
  label={label}
  payload={id}
  // Fires once the activation gesture is met but before anything lifts.
  // Call `eventDetails.cancel()` to veto the drag (see Conditional drag above).
  onBeforeDragStart={({ input }, eventDetails) => {
    if (input.altKey) {
      eventDetails.cancel();
    }
  }}
  // Fires once when the drag starts, after the preview is resolved, so the
  // source is safe to measure or restyle.
  onDragStart={({ source }) => console.log('lifted', source.label)}
  // Fires as the pointer moves, throttled to one call per animation frame.
  // Hover logic belongs on the drop target's `onDrag`, not here.
  onDrag={({ location }) => {
    const { clientX, clientY } = location.current.input;
    console.log('at', clientX, clientY);
  }}
  // Fires when the active drop-target stack changes.
  onDropTargetChange={({ location }) =>
    console.log('over', location.current.dropTargets[0]?.label ?? 'nothing')
  }
  // Fires only when the drag lands on a drop target that accepts it. Apply the
  // change here: reorder the list, move the card into its new column.
  onDrop={({ dropTarget }) => console.log('dropped on', dropTarget.label)}
  // Fires once whatever the ending: a drop, a release over empty space, or a
  // cancel. Use it to undo whatever the drag set up.
  onDragEnd={(event, eventDetails) => console.log('ended:', eventDetails.reason)}
/>

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

Use useDragMonitor to observe every drag on the page instead of one source.

These handlers reuse the native drag event names, so the native HTML drag event props are omitted. As a result, ComponentPropsWithoutRef<'div'> cannot be spread onto Draggable.Root. A wrapper component should declare the element props it forwards instead of exposing every DOM prop:

A wrapper names what it forwards

interface CardProps {
  id: string;
  label: string;
  className?: string;
  style?: React.CSSProperties;
  children?: React.ReactNode;
}

function DraggableCard({ id, label, ...forwarded }: CardProps) {
  return <Draggable.Root kind={card} label={label} payload={id} {...forwarded} />;
}

The native events stay reachable through the render prop, which merges its props onto the rendered element untouched.

Re-rendering the source mid-drag

A drag continues if its source element leaves the DOM. For example, a virtualized list can unmount the dragged row after it scrolls out of view. The drag still moves and drops normally, so the list does not need to keep the row mounted. The same applies when an item is rendered in a different container.

source.element follows a replacement DOM node rendered by the same Draggable.Root instance, such as a virtualizer recycling the row in place. After a complete unmount with no surviving root instance, it remains the last registered node. Read source.payload when you need to identify what is being dragged; if you specifically need stable pickup-node identity, capture source.element in onDragStart:

Identifying the dragged item

<DropTarget.Root accept={card} label="Done" onDrop={({ source }) => move(source.payload)} />

Deleting the dragged item does not end the drag either. Call cancelDrag if you want it to stop:

Ending the drag with the item it was carrying

function deleteCard(id: string) {
  if (id === draggingId) {
    manager.cancelDrag();
  }
  setCards((prev) => prev.filter((card) => card.id !== id));
}

Animating displaced items

Render Draggable.Displacement inside each root that should animate after a reorder. It renders nothing and publishes the offset from the item’s previous position as --drag-displacement-x and --drag-displacement-y. It also adds data-starting-style for the first frame and keeps data-displacing while the animation runs. A synchronous update from onDragEnd is animated after a drop or cancellation. A deferred update is not.

Enable displacement tracking

<Draggable.Root kind={card} payload={cardData}>
  <Draggable.Displacement />
  {cardData.title}
</Draggable.Root>

Define the animation with two CSS rules:

Animating rows to their new slots

.Item[data-displacing][data-starting-style] {
  translate: var(--drag-displacement-x) var(--drag-displacement-y);
}
.Item[data-displacing]:not([data-starting-style]) {
  transition: translate 200ms ease;
}

Do not apply the transition during the data-starting-style frame. This lets an interrupted reorder continue from its current position. Use translate so the displacement composes with an existing transform, and repeat any other transitions replaced by the shorthand. Disable both rules for users who prefer reduced motion. The starting-style rule alone displays the previous position for one frame.

Base UI measures only items in the viewport. Items outside it move to their new position without an animation, so mounted offscreen items do not add layout measurements. An item scrolled into view during a drag uses its current position as the animation start point.

Activation

A pointer press doesn’t start a drag right away. The item is picked up once the gesture reads as a drag rather than a click or a scroll. Mouse and pen activate after the pointer moves 5px; touch activates after a 250ms press-hold, with a 5px movement tolerance, so that scrolling a list still scrolls it. Anything short of that stays a plain click or tap and reaches the element underneath.

The item lifts off exactly where it sat, so the wait never shows up as a jump.

Start

Target

StatusMove 5px while pressed to activate.

index.tsx activation.module.css

'use client';
import * as React from 'react';
import { Draggable } from '@base-ui/react/draggable';
import { DropTarget } from '@base-ui/react/drop-target';
import type { DragActivation } from '@base-ui/react/draggable';
import styles from './activation.module.css';

type Phase = 'ready' | 'waiting' | 'dragging' | 'dropped';

interface ActivationMode {
  id: string;
  label: string;
  activation: DragActivation;
  readyMessage: string;
  waitingMessage: string;
}

const puckKind = Draggable.createKind('activation-puck');

const ACTIVATION_MODES: ActivationMode[] = [
  {
    id: 'immediate',
    label: 'Immediate',
    activation: { type: 'immediate' },
    readyMessage: 'Activates as soon as you press.',
    waitingMessage: 'Activating immediately…',
  },
  {
    id: 'distance-5',
    label: '5 px',
    activation: { type: 'distance', distance: 5 },
    readyMessage: 'Move 5px while pressed to activate.',
    waitingMessage: 'Waiting for 5px of movement…',
  },
  {
    id: 'distance-24',
    label: '24 px',
    activation: { type: 'distance', distance: 24 },
    readyMessage: 'Move 24px while pressed to activate.',
    waitingMessage: 'Waiting for 24px of movement…',
  },
  {
    id: 'press-hold',
    label: 'Hold',
    activation: { type: 'press-hold', delay: 250 },
    readyMessage: 'Press and hold for 250ms to activate.',
    waitingMessage: 'Waiting for the 250ms hold…',
  },
];

function Puck({
  mode,
  onPhaseChange,
}: {
  mode: ActivationMode;
  onPhaseChange: (phase: Phase) => void;
}) {
  return (
    <Draggable.Root
      className={styles.Puck}
      kind={puckKind}
      label="Puck"
      pointerActivation={mode.activation}
      aria-label="Puck"
      role="button"
      onPointerDown={() => {
        if (mode.activation.type !== 'immediate') {
          onPhaseChange('waiting');
        }
      }}
      onPointerUp={() => onPhaseChange('ready')}
      onPointerCancel={() => onPhaseChange('ready')}
      onDragStart={() => onPhaseChange('dragging')}
      onDragEnd={(_, eventDetails) => {
        if (eventDetails.reason !== 'drop') {
          onPhaseChange('ready');
        }
      }}
    />
  );
}

export default function ActivationLab() {
  const [modeId, setModeId] = React.useState('distance-5');
  const [phase, setPhase] = React.useState<Phase>('ready');
  const [dropped, setDropped] = React.useState(false);
  const mode = ACTIVATION_MODES.find((item) => item.id === modeId)!;

  function selectMode(nextModeId: string) {
    setModeId(nextModeId);
    setPhase('ready');
    setDropped(false);
  }

  function reset() {
    setPhase('ready');
    setDropped(false);
  }

  const message = {
    ready: mode.readyMessage,
    waiting: mode.waitingMessage,
    dragging: 'Activated — drag the puck to the target.',
    dropped: 'Dropped. Reset to try again.',
  }[phase];

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

      <div className={styles.Modes} role="group" aria-label="Pointer activation">
        {ACTIVATION_MODES.map((item) => (
          <button
            key={item.id}
            type="button"
            className={styles.Mode}
            aria-pressed={item.id === modeId}
            onClick={() => selectMode(item.id)}
          >
            {item.label}
          </button>
        ))}
      </div>

      <div className={styles.Stage}>
        <div className={styles.Station}>
          <div className={styles.Start}>
            {!dropped && <Puck mode={mode} onPhaseChange={setPhase} />}
          </div>
          <span className={styles.StationLabel}>Start</span>
        </div>

        <div className={styles.Track} aria-hidden="true" />

        <div className={styles.Station}>
          <DropTarget.Root
            className={styles.Target}
            accept={puckKind}
            label="Target"
            onDrop={() => {
              setDropped(true);
              setPhase('dropped');
            }}
          >
            {dropped && <span className={styles.Puck} data-static="" aria-hidden="true" />}
          </DropTarget.Root>
          <span className={styles.StationLabel}>Target</span>
        </div>
      </div>

      <div className={styles.Status} role="status">
        <span className={styles.StatusLabel}>Status</span>
        <span className={styles.StatusMessage}>{message}</span>
      </div>
    </div>
  );
}

Pass pointerActivation to change the thresholds. It takes a single DragActivation applied to every pointer type, or a map keyed by 'mouse', 'touch', and 'pen', where unlisted types keep their defaults. A DragActivation is one of { type: 'immediate' }, { type: 'distance', distance }, or { type: 'press-hold', delay, tolerance? }.

Customizing activation

<Draggable.Root
  kind={card}
  label={label}
  payload={id}
  // Mouse starts after a longer drag; touch after a shorter hold.
  pointerActivation={{
    mouse: { type: 'distance', distance: 10 },
    touch: { type: 'press-hold', delay: 150 },
  }}
/>

Use { type: 'immediate' } to pick the item up on the first pointerdown, with no travel. This is a good fit for a canvas where the whole tile is a drag affordance. Avoid it when the item contains buttons or links: a click on them would start a drag instead.

Instant pickup

<Draggable.Root kind={tile} label={label} payload={id} pointerActivation={{ type: 'immediate' }} />

Draggable.Root is focusable by default and supports keyboard dragging. Focus a source and use these keys:

Space or Enter picks the item up.
Arrow keys move it toward the nearest drop target in the pressed direction. With no target that way, the item nudges by a fixed step instead (hold Shift for a coarser one), so free-form dragging still works.
Space or Enter drops it; Escape or Tab cancels.

Visitors

2,420Last 7 days

Conversion

3.8%Up 0.4%

Drop widget

index.tsx keyboard.module.css

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

type SlotId = 'left' | 'center' | 'right';

interface WidgetData {
  id: string;
  title: string;
  value: string;
  detail: string;
  slot: SlotId;
}

const widgetKind = Draggable.createKind<string>('draggable/keyboard-widget');

const SLOTS: { id: SlotId; label: string }[] = [
  { id: 'left', label: 'Left dashboard slot' },
  { id: 'center', label: 'Center dashboard slot' },
  { id: 'right', label: 'Right dashboard slot' },
];

const INITIAL_WIDGETS: WidgetData[] = [
  { id: 'visitors', title: 'Visitors', value: '2,420', detail: 'Last 7 days', slot: 'left' },
  { id: 'conversion', title: 'Conversion', value: '3.8%', detail: 'Up 0.4%', slot: 'center' },
];

function Grip() {
  return (
    <svg className={styles.Grip} width="8" height="14" viewBox="0 0 8 14" aria-hidden="true">
      <g fill="currentColor">
        <circle cx="2" cy="2" r="1.2" />
        <circle cx="6" cy="2" r="1.2" />
        <circle cx="2" cy="7" r="1.2" />
        <circle cx="6" cy="7" r="1.2" />
        <circle cx="2" cy="12" r="1.2" />
        <circle cx="6" cy="12" r="1.2" />
      </g>
    </svg>
  );
}

function Widget({ widget }: { widget: WidgetData }) {
  return (
    <Draggable.Root
      label={`${widget.title} widget`}
      kind={widgetKind}
      payload={widget.id}
      role="button"
      className={styles.Widget}
    >
      <div className={styles.WidgetHeader}>
        <Grip />
        <span>{widget.title}</span>
      </div>
      <div className={styles.WidgetBody}>
        <strong>{widget.value}</strong>
        <span>{widget.detail}</span>
      </div>
    </Draggable.Root>
  );
}

function DockSlot({
  id,
  label,
  widget,
  onMoveWidget,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
}) {
  return (
    <DropTarget.Root
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      label={label}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? <Widget widget={widget} /> : <span className={styles.Empty}>Drop widget</span>}
    </DropTarget.Root>
  );
}

export default function KeyboardDashboard() {
  const [widgets, setWidgets] = React.useState<WidgetData[]>(INITIAL_WIDGETS);

  function moveWidget(widgetId: string, slot: SlotId) {
    setWidgets((currentWidgets) =>
      currentWidgets.map((widget) => (widget.id === widgetId ? { ...widget, slot } : widget)),
    );
  }

  return (
    <div className={styles.Root}>
      <div className={styles.Grid}>
        {SLOTS.map((slot) => (
          <DockSlot
            key={slot.id}
            id={slot.id}
            label={slot.label}
            widget={widgets.find((widget) => widget.slot === slot.id)}
            onMoveWidget={moveWidget}
          />
        ))}
      </div>
    </div>
  );
}

The widgets above use plain draggables and drop targets with no keyboard-specific code. Each slot has a label so announcements can name it. Pressing ← or → moves the focused widget to the next accepting slot in that direction. The same behavior applies to any draggable and drop target, including reorderable collections.

The source must be focusable. When keyboard dragging is enabled without a Draggable.Handle, Draggable.Root defaults to tabIndex={0} and role="button". A handle renders its own focusable button. Pass tabIndex or role to override either default. Override the role if the element already has semantics such as listitem or row. Prefer a handle when the source contains interactive children because a button cannot contain other interactive elements. When using registerDraggable, make the registered element focusable.

The default tabIndex and role are added after mount, once the root knows whether it has a handle. Pass them explicitly when a server-rendered draggable must be keyboard-reachable before hydration.

Pickup, drop, and cancel are announced automatically. The default announcement uses the item’s label, for example, “Grabbed Water the plants…", followed by the keyboard instructions. Without a label, it uses “item”. Add a label to each DropTarget.Root to announce the destination. For example, moving over a target announces “Water the plants on Done”, and dropping announces “Dropped Water the plants on Done.” Moves over an unlabeled target are silent, and its drop announcement omits the destination.

Pass keyboardAnnouncements.moved (and any of pickedUp, dropped, canceled) to narrate moves yourself. Each callback returns the string to announce, or null to stay silent:

Announcing each keyboard move

<Draggable.Root
  kind={card}
  label={label}
  payload={id}
  keyboardAnnouncements={{
    moved: ({ location }) => {
      const count = location.current.dropTargets.length;
      return count > 0 ? 'Over a drop target' : null;
    },
  }}
/>

For localized strings across every draggable, provide them through LocalizationProvider instead of per-source. Two more per-source options tune what assistive tech reads: ariaRoleDescription sets the handle’s aria-roledescription (a localized “draggable” by default), and keyboardInstructions replaces the instructions announced when the handle is focused.

Controlling movement

By default, an arrow key moves to the nearest drop target or by a fixed step when no target is ahead. Use keyboardMovement when the component has its own movement rules. The callback receives the pressed key, drag context, default suggestion, and the findTarget and getTargets helpers. Its return value controls the move:

{ x, y } moves the cursor to those client coordinates, clamped to the viewport. Base UI does not apply an extra Shift multiplier.
An Element scrolls into view and becomes the destination. Use this to reach an element outside the viewport.
The suggestion accepts the default move, with an optional adjusted position. Returning { type: 'target', element, position } moves onto an element while preserving a coordinate, such as the same height in the adjacent column.
false handles the key without moving.
null or undefined uses the default behavior for that key.

In a sortable list or a board, free space is never a valid position, so the step-nudge fallback only lets the preview drift into dead space. Draggable.targetsOnlyKeyboardMovement is a prebuilt resolver for exactly that: arrows only ever move between accepting drop targets, and a press past the last one does nothing. The sortable list demo uses it.

Arrows only move between items

<Draggable.Root
  kind={card}
  label={label}
  payload={id}
  keyboardMovement={Draggable.targetsOnlyKeyboardMovement}
/>

On a free-form canvas, every point is valid. Moving to the nearest target could send the source across the canvas unexpectedly. Draggable.fixedStepKeyboardMovement(step) instead moves by step without checking targets. Holding Shift moves four times as far.

Arrows nudge by a fixed step

<Draggable.Root
  kind={card}
  label={label}
  payload={id}
  keyboardMovement={Draggable.fixedStepKeyboardMovement(20)}
/>

The step is in the source’s own coordinate space, so a zoomable canvas moves the source the same distance on the board at any zoom. Write your own resolver when the step depends on more than direction:

Fine-grained pixel movement

<Draggable.Root
  kind={card}
  label={label}
  payload={id}
  keyboardMovement={({ position, direction, shiftKey }) => ({
    x: position.x + direction.x * (shiftKey ? 32 : 4),
    y: position.y + direction.y * (shiftKey ? 32 : 4),
  })}
/>

For a grid with custom movement rules, see the calendar example. Vertical movement changes the time, while horizontal movement changes the day. Return false to refuse a key press and call keyboardAnnouncements.reachedEdge, which is silent by default. Return null or undefined to use the default movement.

Restoring focus

When a keyboard drag ends, Base UI tries to focus the handle, source, and then innermost drop target. Pointer drags never move focus. Use finalFocus to choose another element. Pass false to leave focus unchanged, a ref, or a function that returns the element to focus. From the function, return true or null for the default behavior. Return false or undefined to leave focus unchanged.

Visitors

2,420Last 7 days

Conversion

3.8%Up 0.4%

Drop widget

Note

index.tsx focus.module.css

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

type SlotId = 'left' | 'center' | 'right';

interface WidgetData {
  id: string;
  title: string;
  value: string;
  detail: string;
  slot: SlotId;
}

const widgetKind = Draggable.createKind<string>('draggable/focus-widget');

const SLOTS: { id: SlotId; label: string }[] = [
  { id: 'left', label: 'Left dashboard slot' },
  { id: 'center', label: 'Center dashboard slot' },
  { id: 'right', label: 'Right dashboard slot' },
];

const INITIAL_WIDGETS: WidgetData[] = [
  { id: 'visitors', title: 'Visitors', value: '2,420', detail: 'Last 7 days', slot: 'left' },
  { id: 'conversion', title: 'Conversion', value: '3.8%', detail: 'Up 0.4%', slot: 'center' },
];

function Grip() {
  return (
    <svg className={styles.Grip} width="8" height="14" viewBox="0 0 8 14" aria-hidden="true">
      <g fill="currentColor">
        <circle cx="2" cy="2" r="1.2" />
        <circle cx="6" cy="2" r="1.2" />
        <circle cx="2" cy="7" r="1.2" />
        <circle cx="6" cy="7" r="1.2" />
        <circle cx="2" cy="12" r="1.2" />
        <circle cx="6" cy="12" r="1.2" />
      </g>
    </svg>
  );
}

function Widget({
  widget,
  noteRef,
}: {
  widget: WidgetData;
  noteRef: React.RefObject<HTMLInputElement | null>;
}) {
  return (
    <Draggable.Root
      label={`${widget.title} widget`}
      kind={widgetKind}
      payload={widget.id}
      finalFocus={({ dropTarget }) => (dropTarget ? noteRef.current : true)}
      role="button"
      className={styles.Widget}
    >
      <div className={styles.WidgetHeader}>
        <Grip />
        <span>{widget.title}</span>
      </div>
      <div className={styles.WidgetBody}>
        <strong>{widget.value}</strong>
        <span>{widget.detail}</span>
      </div>
    </Draggable.Root>
  );
}

function DockSlot({
  id,
  label,
  widget,
  noteRef,
  onMoveWidget,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  noteRef: React.RefObject<HTMLInputElement | null>;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
}) {
  return (
    <DropTarget.Root
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      label={label}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? (
        <Widget widget={widget} noteRef={noteRef} />
      ) : (
        <span className={styles.Empty}>Drop widget</span>
      )}
    </DropTarget.Root>
  );
}

export default function FocusDashboard() {
  const [widgets, setWidgets] = React.useState<WidgetData[]>(INITIAL_WIDGETS);
  const noteRef = React.useRef<HTMLInputElement | null>(null);

  function moveWidget(widgetId: string, slot: SlotId) {
    setWidgets((currentWidgets) =>
      currentWidgets.map((widget) => (widget.id === widgetId ? { ...widget, slot } : widget)),
    );
  }

  return (
    <div className={styles.Root}>
      <div className={styles.Grid}>
        {SLOTS.map((slot) => (
          <DockSlot
            key={slot.id}
            id={slot.id}
            label={slot.label}
            widget={widgets.find((widget) => widget.slot === slot.id)}
            noteRef={noteRef}
            onMoveWidget={moveWidget}
          />
        ))}
      </div>
      <label className={styles.Field}>
        <span className={styles.FieldLabel}>Note</span>
        <input ref={noteRef} className={styles.Note} placeholder="Add a note about the move…" />
      </label>
    </div>
  );
}

Moving the pickup elsewhere

Space picks up a draggable, but many elements already use that key. A calendar event may open a menu, Space may select a listbox option, or a card may expand. One key press cannot perform both actions.

Set keyboardActivation="manual" to keep Space and Enter for the element. Start the drag from the appropriate control by calling useDragDropManager().startKeyboardDrag(element). Announcements and focus restoration work the same as for an automatically started keyboard drag.

A drag started from the widget's own menu

function Widget({ widget }) {
  const manager = useDragDropManager();
  const ref = React.useRef<HTMLButtonElement>(null);
  const startOnCloseRef = React.useRef(false);

  return (
    <Menu.Root
      onOpenChangeComplete={(open) => {
        if (!open && startOnCloseRef.current) {
          startOnCloseRef.current = false;
          manager.startKeyboardDrag(ref.current);
        }
      }}
    >
      <Draggable.Root
        kind={widgetKind}
        label={`${widget.title} widget`}
        payload={widget.id}
        keyboardActivation="manual"
        keyboardInstructions="Press Space to open the widget menu, then choose Move to move it."
        render={<Menu.Trigger render={<button ref={ref} type="button" />} />}
      >
        {widget.title}
      </Draggable.Root>
      <Menu.Popup>
        <Menu.Item
          onClick={() => {
            startOnCloseRef.current = true;
          }}
        >
          Move
        </Menu.Item>
      </Menu.Popup>
    </Menu.Root>
  );
}

The element stays focusable and is still announced as draggable. Because Base UI does not know which control starts the drag, it omits the default “press Space to lift” instructions. Use keyboardInstructions to describe how to start the drag.

index.tsx menu-drag.module.css

'use client';
import * as React from 'react';
import { Menu } from '@base-ui/react/menu';
import { Draggable } from '@base-ui/react/draggable';
import { DropTarget } from '@base-ui/react/drop-target';
import { useDragDropManager } from '@base-ui/react/use-drag-drop-manager';
import styles from './menu-drag.module.css';

type SlotId = 'left' | 'center' | 'right';

interface WidgetData {
  id: string;
  title: string;
  value: string;
  detail: string;
  slot: SlotId;
}

const widgetKind = Draggable.createKind<string>('draggable/menu-widget');

const SLOTS: { id: SlotId; label: string }[] = [
  { id: 'left', label: 'Left dashboard slot' },
  { id: 'center', label: 'Center dashboard slot' },
  { id: 'right', label: 'Right dashboard slot' },
];

const INITIAL_WIDGETS: WidgetData[] = [
  { id: 'visitors', title: 'Visitors', value: '2,420', detail: 'Last 7 days', slot: 'left' },
  { id: 'conversion', title: 'Conversion', value: '3.8%', detail: 'Up 0.4%', slot: 'center' },
];

function Grip() {
  return (
    <svg className={styles.Grip} width="8" height="14" viewBox="0 0 8 14" aria-hidden="true">
      <g fill="currentColor">
        <circle cx="2" cy="2" r="1.2" />
        <circle cx="6" cy="2" r="1.2" />
        <circle cx="2" cy="7" r="1.2" />
        <circle cx="6" cy="7" r="1.2" />
        <circle cx="2" cy="12" r="1.2" />
        <circle cx="6" cy="12" r="1.2" />
      </g>
    </svg>
  );
}

function MoreIcon() {
  return (
    <svg className={styles.MoreIcon} width="14" height="14" viewBox="0 0 14 14" aria-hidden="true">
      <circle cx="3" cy="7" r="1" fill="currentColor" />
      <circle cx="7" cy="7" r="1" fill="currentColor" />
      <circle cx="11" cy="7" r="1" fill="currentColor" />
    </svg>
  );
}

function Widget({ widget, onRemove }: { widget: WidgetData; onRemove: (id: string) => void }) {
  const manager = useDragDropManager();
  const ref = React.useRef<HTMLButtonElement | null>(null);
  const [openedByKeyboard, setOpenedByKeyboard] = React.useState(false);
  const startOnCloseRef = React.useRef(false);

  return (
    <Menu.Root
      onOpenChange={(open, eventDetails) => {
        if (open) {
          setOpenedByKeyboard((eventDetails.event as MouseEvent).detail === 0);
        }
      }}
      onOpenChangeComplete={(open) => {
        if (!open && startOnCloseRef.current) {
          startOnCloseRef.current = false;
          manager.startKeyboardDrag(ref.current);
        }
      }}
    >
      <Draggable.Root
        kind={widgetKind}
        payload={widget.id}
        label={`${widget.title} widget`}
        keyboardActivation="manual"
        keyboardInstructions="Press Space to open the widget menu, then choose Move to move it."
        render={
          <Menu.Trigger render={<button ref={ref} type="button" aria-label={widget.title} />} />
        }
        className={styles.Widget}
      >
        <span className={styles.WidgetHeader}>
          <Grip />
          <span>{widget.title}</span>
          <MoreIcon />
        </span>
        <span className={styles.WidgetBody}>
          <strong>{widget.value}</strong>
          <span>{widget.detail}</span>
        </span>
      </Draggable.Root>
      <Menu.Portal>
        <Menu.Positioner sideOffset={4}>
          <Menu.Popup className={styles.Popup}>
            {openedByKeyboard && (
              <Menu.Item
                className={styles.MenuItem}
                onClick={() => {
                  startOnCloseRef.current = true;
                }}
              >
                Move
              </Menu.Item>
            )}
            <Menu.Item className={styles.MenuItem} onClick={() => onRemove(widget.id)}>
              Remove
            </Menu.Item>
          </Menu.Popup>
        </Menu.Positioner>
      </Menu.Portal>
    </Menu.Root>
  );
}

function DockSlot({
  id,
  label,
  widget,
  onMoveWidget,
  onRemoveWidget,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
  onRemoveWidget: (widgetId: string) => void;
}) {
  return (
    <DropTarget.Root
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      label={label}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? (
        <Widget widget={widget} onRemove={onRemoveWidget} />
      ) : (
        <span className={styles.Empty}>Drop widget</span>
      )}
    </DropTarget.Root>
  );
}

export default function WidgetMenuDashboard() {
  const [widgets, setWidgets] = React.useState<WidgetData[]>(INITIAL_WIDGETS);

  function moveWidget(widgetId: string, slot: SlotId) {
    setWidgets((currentWidgets) =>
      currentWidgets.map((widget) => (widget.id === widgetId ? { ...widget, slot } : widget)),
    );
  }

  return (
    <div className={styles.Root}>
      <div className={styles.Grid}>
        {SLOTS.map((slot) => (
          <DockSlot
            key={slot.id}
            id={slot.id}
            label={slot.label}
            widget={widgets.find((widget) => widget.slot === slot.id)}
            onMoveWidget={moveWidget}
            onRemoveWidget={(widgetId) =>
              setWidgets((currentWidgets) =>
                currentWidgets.filter((widget) => widget.id !== widgetId),
              )
            }
          />
        ))}
      </div>
    </div>
  );
}

Each widget above is a menu trigger, so Space opens the menu and Move starts the drag. Then ← and → choose an empty dashboard slot, and Space drops the widget.

Show Move only when the menu was opened with the keyboard. Pointer users can drag the widget directly.
Start the drag from onOpenChangeComplete after the menu closes, not from the item’s onClick. Closing the menu returns focus to its trigger before the drag starts.

Pass keyboardActivation="off" to disable keyboard dragging. The element stays pointer-draggable. Base UI leaves every key to your handlers and omits the keyboard-drag instructions, tabIndex, and role defaults. Use this only when another control provides the same keyboard action, or when the draggable is aria-hidden decoration such as a resize handle.

Movement modifiers

A drag follows the pointer freely by default. Pass modifiers to keep it on one axis, snap it to a grid, or hold it inside an element. The same modifiers apply to pointer and keyboard drags. They constrain the preview, drop hit test, and keyboard cursor.

Locking a sortable list to one axis

<Draggable.Root
  kind={card}
  label={label}
  payload={id}
  modifiers={Draggable.restrictToVerticalAxis}
/>

The prebuilt modifiers:

restrictToVerticalAxis and restrictToHorizontalAxis lock the drag to one axis, anchored where it began.
restrictToParentElement keeps it inside the source’s parent, and restrictToElement(target) inside any element, ref, or function returning one.
restrictToWindowEdges keeps it inside the viewport.
snapToGrid(size) snaps to a grid anchored at the pickup point. Pass a number or { x, y } for a rectangular grid. The step uses the source’s coordinate system. For example, snapToGrid(20) still snaps to a 20-unit grid when the canvas is zoomed to 70%.

Pass an array to combine them, each clamping the previous one’s result.

Combining modifiers

<Draggable.Root
  kind={tile}
  label={label}
  payload={id}
  modifiers={[Draggable.snapToGrid(20), Draggable.restrictToParentElement]}
/>

Below, restrictToElement clamps each widget to the dashed dashboard frame. The preview and drop hit test cannot leave the frame, so the outside slot never activates. Write a custom modifier for behavior the presets do not cover, such as snapping to calendar slots. See Write your own and the calendar example.

Visitors

2,420Last 7 days

Conversion

3.8%Up 0.4%

Drop widget

Outside slotThe drag cannot reach this target.

index.tsx containment.module.css

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

type SlotId = 'left' | 'center' | 'right';

interface WidgetData {
  id: string;
  title: string;
  value: string;
  detail: string;
  slot: SlotId;
}

const widgetKind = Draggable.createKind<string>('draggable/contained-widget');

const SLOTS: { id: SlotId; label: string }[] = [
  { id: 'left', label: 'Left dashboard slot' },
  { id: 'center', label: 'Center dashboard slot' },
  { id: 'right', label: 'Right dashboard slot' },
];

const INITIAL_WIDGETS: WidgetData[] = [
  { id: 'visitors', title: 'Visitors', value: '2,420', detail: 'Last 7 days', slot: 'left' },
  { id: 'conversion', title: 'Conversion', value: '3.8%', detail: 'Up 0.4%', slot: 'center' },
];

function Grip() {
  return (
    <svg className={styles.Grip} width="8" height="14" viewBox="0 0 8 14" aria-hidden="true">
      <g fill="currentColor">
        <circle cx="2" cy="2" r="1.2" />
        <circle cx="6" cy="2" r="1.2" />
        <circle cx="2" cy="7" r="1.2" />
        <circle cx="6" cy="7" r="1.2" />
        <circle cx="2" cy="12" r="1.2" />
        <circle cx="6" cy="12" r="1.2" />
      </g>
    </svg>
  );
}

function Widget({
  widget,
  frameRef,
}: {
  widget: WidgetData;
  frameRef: React.RefObject<HTMLDivElement | null>;
}) {
  return (
    <Draggable.Root
      label={`${widget.title} widget`}
      kind={widgetKind}
      payload={widget.id}
      role="button"
      className={styles.Widget}
      modifiers={Draggable.restrictToElement(frameRef)}
    >
      <div className={styles.WidgetHeader}>
        <Grip />
        <span>{widget.title}</span>
      </div>
      <div className={styles.WidgetBody}>
        <strong>{widget.value}</strong>
        <span>{widget.detail}</span>
      </div>
    </Draggable.Root>
  );
}

function DockSlot({
  id,
  label,
  widget,
  frameRef,
  onMoveWidget,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  frameRef: React.RefObject<HTMLDivElement | null>;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
}) {
  return (
    <DropTarget.Root
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      label={label}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? (
        <Widget widget={widget} frameRef={frameRef} />
      ) : (
        <span className={styles.Empty}>Drop widget</span>
      )}
    </DropTarget.Root>
  );
}

export default function ContainedDashboard() {
  const [widgets, setWidgets] = React.useState<WidgetData[]>(INITIAL_WIDGETS);
  const frameRef = React.useRef<HTMLDivElement | null>(null);

  function moveWidget(widgetId: string, slot: SlotId) {
    setWidgets((currentWidgets) =>
      currentWidgets.map((widget) => (widget.id === widgetId ? { ...widget, slot } : widget)),
    );
  }

  return (
    <div className={styles.Root}>
      <div ref={frameRef} className={styles.Frame}>
        <div className={styles.Grid}>
          {SLOTS.map((slot) => (
            <DockSlot
              key={slot.id}
              id={slot.id}
              label={slot.label}
              widget={widgets.find((widget) => widget.slot === slot.id)}
              frameRef={frameRef}
              onMoveWidget={moveWidget}
            />
          ))}
        </div>
      </div>
      <DropTarget.Root className={styles.OutsideSlot} label="Outside slot" accept={widgetKind}>
        <strong>Outside slot</strong>
        <span>The drag cannot reach this target.</span>
      </DropTarget.Root>
    </div>
  );
}

Modifiers on the preview

Draggable.Preview and Draggable.ClonedPreview take the same modifiers prop. These modifiers affect only the preview. The drop hit test, keyboard movement, and reported input remain unconstrained. Use preview modifiers when leaving an area must still cancel the drag. For example, a data grid can keep the preview inside the grid while allowing a release outside it to cancel instead of dropping on the nearest header. Otherwise, put the modifier on Draggable.Root so the preview position matches the drop position.

Write your own

A modifier takes the point the engine would use and returns the point to use instead. Alongside point, it receives where the drag began (initialPoint), the cursor (input), the source and preview rects, scale, and the modifier keys held by the event that produced the move. It runs on every frame of a pointer drag and on every keyboard press, so keep it cheap.

Snapping to fixed rows

import type { DragModifier } from '@base-ui/react/draggable';

const snapToRows: DragModifier = ({ point }) => ({
  x: point.x,
  y: nearest(ROW_TOPS, point.y),
});

Points use client pixels, which match measurements from the viewport or another element’s bounding rect. To work in a zoomable canvas’s coordinate system, multiply distances by scale. The value includes CSS transform and zoom scaling applied to the source or its ancestors. It is 1 when the source is not scaled. A rotation alone does not change it. The snapToGrid preset uses this value.

A step measured on the canvas, not the screen

const nudgeRight: DragModifier = ({ point, scale }) => ({
  x: point.x + 20 * scale.x,
  y: point.y,
});

Gating on a modifier key

ctrlKey, shiftKey, altKey, and metaKey report the keys held for the event that produced the move. For example, a drawing tool can bind “snap to 45°” to Shift. During a pointer drag, pressing or releasing a modifier key reapplies the modifiers on the next frame. During a keyboard drag, these fields report the keys held for each arrow press. Ctrl, Alt, and Meta chords remain available for other shortcuts.

Snapping to 45° while Shift is held

const snapToAngle: DragModifier = ({ point, mode, shiftKey, initialPoint }) => {
  // Pointer only: Shift already means "travel further" to a keyboard drag.
  if (mode !== 'pointer' || !shiftKey) {
    return point;
  }
  // Project the drag onto the nearest 45° ray from where it began.
  const dx = point.x - initialPoint.x;
  const dy = point.y - initialPoint.y;
  const angle = Math.round(Math.atan2(dy, dx) / (Math.PI / 4)) * (Math.PI / 4);
  const distance = dx * Math.cos(angle) + dy * Math.sin(angle);
  return {
    x: initialPoint.x + Math.cos(angle) * distance,
    y: initialPoint.y + Math.sin(angle) * distance,
  };
};

Check mode with the modifier keys. The same key can behave differently for pointer and keyboard drags. For example, Shift increases the step for fixedStepKeyboardMovement, so a pointer-only Shift modifier should also require mode === 'pointer'.

A modifier only moves a point, so it still can’t express a keyboard move that targets a specific element or refuses the press. Use keyboardMovement for those.

Drag previews

Default preview

With no preview part, a sanitized clone of the dragged element follows the pointer. The clone keeps your element’s classes and live form, canvas, and scroll state, and renders in the browser’s top layer, where no scroll container can clip it and nothing on the page paints over it.

The clone rewrites its IDs to keep the document unique and updates fragment references inside the clone. External #id selectors therefore do not style it; use classes or [data-drag-preview] for preview styles.

Custom elements inside a clone are replaced with inert native placeholders. Cloning a live custom element would run its constructor and connection callbacks again merely because a drag started. Render a Draggable.Preview when the preview must reproduce a custom element’s shadow content exactly.

Base UI reads the computed style of each custom element to size and style its inert placeholder. For a draggable containing many custom elements, use a lightweight Draggable.Preview to avoid doing that work when the drag starts.

After a release, the clone moves to the source’s final position and receives data-ending-style. That includes a release outside a target, when it returns to the unchanged source. Add a translate transition under that attribute to animate the handoff; the engine keeps the clone mounted until the transition finishes. The source also receives data-ending-style alongside data-dragging, so it can remain styled as an empty placeholder until the clone arrives. With no transition, the attributes and clone are removed before the next paint.

Animating the preview into its final position

.Card[data-drag-preview][data-ending-style] {
  transition: translate 200ms ease;
}

Cloning cannot reproduce every browser state. Render a Draggable.Preview in these cases:

Content drawn outside the DOM: a WebGL <canvas>, a playing <video>, an element’s shadow DOM. Form values, canvas drawings and scroll positions are carried over.
:hover, :focus and :focus-within don’t apply to the preview, so styles that depend on them render in their resting state.
A bare native control, such as an unstyled <button> or <input>, loses its default browser chrome in the top layer. Give it your own styles, or use a Draggable.Preview.

Custom previews

To show something other than a clone, render a Draggable.Preview inside the root. Its children become the preview. Like the clone, it is placed next to the element it was lifted from, so your CSS reaches it the same way.

Keep pointer-events: none on the preview and its children. Base UI sets it on the preview element so hit testing reaches the drop targets underneath. If a child overrides it with pointer-events: auto, Base UI must hide the preview and repeat the hit test on every drag frame.

The dashboard below drags each widget as a compact badge instead of a copy of itself.

Visitors

2,420Last 7 days

Conversion

3.8%Up 0.4%

Drop widget

index.tsx badge.module.css

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

type SlotId = 'left' | 'center' | 'right';

interface WidgetData {
  id: string;
  title: string;
  value: string;
  detail: string;
  slot: SlotId;
}

const widgetKind = Draggable.createKind<string>('draggable/preview-widget');

const SLOTS: { id: SlotId; label: string }[] = [
  { id: 'left', label: 'Left dashboard slot' },
  { id: 'center', label: 'Center dashboard slot' },
  { id: 'right', label: 'Right dashboard slot' },
];

const INITIAL_WIDGETS: WidgetData[] = [
  { id: 'visitors', title: 'Visitors', value: '2,420', detail: 'Last 7 days', slot: 'left' },
  { id: 'conversion', title: 'Conversion', value: '3.8%', detail: 'Up 0.4%', slot: 'center' },
];

function Grip() {
  return (
    <svg className={styles.Grip} width="8" height="14" viewBox="0 0 8 14" aria-hidden="true">
      <g fill="currentColor">
        <circle cx="2" cy="2" r="1.2" />
        <circle cx="6" cy="2" r="1.2" />
        <circle cx="2" cy="7" r="1.2" />
        <circle cx="6" cy="7" r="1.2" />
        <circle cx="2" cy="12" r="1.2" />
        <circle cx="6" cy="12" r="1.2" />
      </g>
    </svg>
  );
}

function Widget({ widget }: { widget: WidgetData }) {
  return (
    <Draggable.Root
      label={`${widget.title} widget`}
      kind={widgetKind}
      payload={widget.id}
      role="button"
      className={styles.Widget}
    >
      <div className={styles.WidgetHeader}>
        <Grip />
        <span>{widget.title}</span>
      </div>
      <div className={styles.WidgetBody}>
        <strong>{widget.value}</strong>
        <span>{widget.detail}</span>
      </div>
      <Draggable.Preview className={styles.Badge} offset="pointer">
        <span className={styles.BadgeValue}>{widget.value}</span>
        {widget.title}
      </Draggable.Preview>
    </Draggable.Root>
  );
}

function DockSlot({
  id,
  label,
  widget,
  onMoveWidget,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
}) {
  return (
    <DropTarget.Root
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      label={label}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? <Widget widget={widget} /> : <span className={styles.Empty}>Drop widget</span>}
    </DropTarget.Root>
  );
}

export default function CustomPreviewDashboard() {
  const [widgets, setWidgets] = React.useState<WidgetData[]>(INITIAL_WIDGETS);

  function moveWidget(widgetId: string, slot: SlotId) {
    setWidgets((currentWidgets) =>
      currentWidgets.map((widget) => (widget.id === widgetId ? { ...widget, slot } : widget)),
    );
  }

  return (
    <Draggable.PreviewProvider>
      <div className={styles.Root}>
        <div className={styles.Grid}>
          {SLOTS.map((slot) => (
            <DockSlot
              key={slot.id}
              id={slot.id}
              label={slot.label}
              widget={widgets.find((widget) => widget.slot === slot.id)}
              onMoveWidget={moveWidget}
            />
          ))}
        </div>
      </div>
    </Draggable.PreviewProvider>
  );
}

A badge instead of a clone

import { Draggable } from '@base-ui/react/draggable';

function Widget({ id, title, value }) {
  return (
    <Draggable.Root kind={widgetKind} label={`${title} widget`} payload={id}>
      {title}
      {/* The badge is much smaller than the widget, so keep it under the pointer. */}
      <Draggable.Preview className="Badge" offset="pointer">
        <span>{value}</span>
        {title}
      </Draggable.Preview>
    </Draggable.Root>
  );
}

The content renders beside the nearest Draggable.PreviewProvider‘s children and outlives the source when a virtualizer or a live reorder unmounts it mid-drag. It receives context from providers above that preview provider, but not from providers nested between the preview provider and this draggable. Place a preview provider inside each local theme, direction, or store boundary the preview needs. The element itself still sits next to the source, so your CSS reaches it either way.

Pass a function as the children to build the preview from the dragged item’s data. To match the source size, use the --drag-source-width and --drag-source-height CSS variables. See Sizing a custom preview.

To show no preview for a particular drag, resolve the children to nothing: null, or a falsy {condition && …}. The engine tears down the host it had already built, so nothing follows the pointer for that drag. To switch the preview off for good, see Drag without a preview.

Configure the clone

To configure how the default clone is placed, render a Draggable.ClonedPreview. It takes the same placement props as Draggable.Preview and renders nothing, since the clone is the engine’s and there’s no content to own:

Place the clone under the pointer

function Card({ id, label }) {
  return (
    <Draggable.Root kind={card} label={label} payload={id}>
      {label}
      <Draggable.ClonedPreview offset="pointer" />
    </Draggable.Root>
  );
}

You only need this part to configure the clone. Style the clone with [data-drag-preview]. The part renders no element of its own, so it takes no className.

Drag without a preview

Use disabled on a preview part when nothing should follow the pointer. The drag still runs, so targets receive drag state and the drop can complete. This is useful for a canvas that draws its own drag feedback. Draggable.ClonedPreview needs no preview provider, even when disabled.

Dragging without a preview

<Draggable.Root kind={shape} label={label} payload={id}>
  {label}
  <Draggable.ClonedPreview disabled />
</Draggable.Root>

Position the preview

Use offset to place the preview relative to the pointer. It defaults to 'source', which keeps the exact grab point the element was picked up by, so the preview lifts off without shifting.

offset works the same on Draggable.Preview and Draggable.ClonedPreview. A Draggable.Preview with no children resolves to no preview at all, so give it content. Use Draggable.ClonedPreview, as shown here, to position the clone.

Place the preview relative to the pointer

// The grab point (default): the preview lifts off the source in place.
<Draggable.ClonedPreview offset="source" />

// The pointer: the preview's top-left sits under the cursor.
<Draggable.ClonedPreview offset="pointer" />

// A fixed distance from the pointer.
<Draggable.Preview offset={{ x: 12, y: 12 }}>{label}</Draggable.Preview>

// Computed at drag start, centering the preview under the pointer.
<Draggable.Preview
  offset={({ container }) => ({
    x: container.offsetWidth / 2,
    y: container.offsetHeight / 2,
  })}
>
  {label}
</Draggable.Preview>

Render previews elsewhere

Previews render as the last of the source’s siblings, so for the duration of the drag an extra element sits in the list. Two things notice:

Selectors that count from the end of the list shift, so :last-child, :only-child, and :nth-last-child rules on siblings can flicker. The :nth-child selector is unaffected because it counts from the start.
DOM scans see it. If you querySelectorAll the siblings to work out where a drop lands, filter the preview out:
Skip the preview when scanning
```
const cards = list.querySelectorAll('[data-card]:not([data-drag-preview])');
```

To avoid both, pass container to inject the preview elsewhere. It accepts an element, a ref, or a callback that resolves the container from the source. The callback is useful when the item has no ref:

Render previews outside the list

<Draggable.Preview container={(source) => source.closest('.Board')}>{label}</Draggable.Preview>

Set it on Draggable.PreviewProvider to apply to every source inside it, with no per-item prop. A preview’s own container wins over that:

One container for the whole board

<Draggable.PreviewProvider container={boardRef}>
  <Board ref={boardRef} />
</Draggable.PreviewProvider>

Prefer the closest suitable container. The preview no longer has the source’s ancestors, so selectors such as .Column .Card stop matching. A nearby themed wrapper preserves more of the cascade than a container near the document root. Rules based on the preview’s own classes still apply. Its DOM container does not affect React context.

Set the drag cursor

While a pointer drag is in progress the cursor is pinned to grabbing across the whole document, so it stays consistent no matter what is under the pointer. Pass a different CSS cursor as dragCursor, or dragCursor={false} to manage it yourself.

Set the cursor for the drag

<Draggable.Root kind={card} label={label} payload={{ id }} dragCursor="move" />

API reference

The payload type declared by kind flows to the root’s event handlers and keyboard callbacks.

Root

labelstring—

Name: label
Description: Human-readable name of this draggable, used by the default screen-reader announcements for keyboard drags. Defaults to a generic “item”. For full control over the announcement text, use keyboardAnnouncements instead.
Type: string | undefined

ariaRoleDescriptionstring—

Name: ariaRoleDescription
Description: Value for aria-roledescription on the drag handle, announcing the element as draggable to screen readers. Defaults to the text of the nearest LocalizationProvider.
Type: string | undefined

dragCursorstring | false'grabbing'

Name: dragCursor
Description: CSS cursor applied across the document during a pointer drag. The drag preview has pointer-events: none, so otherwise the cursor would depend on the element under the pointer. Touch drags ignore this value. Pass false to manage the cursor yourself.
Type: string | false | undefined
Default: 'grabbing'

getPayloadfunction—

Name: getPayload
Description: Resolves payload data from the current drag context.
Type: | DraggablePayloadGetter<TData> | DraggablePayloadGetter<undefined> | undefined

keyboardActivationDragKeyboardActivation'auto'

Name: keyboardActivation
Description: How keyboard dragging is started. See DragKeyboardActivation for the supported modes.
Type: DragKeyboardActivation | undefined
Default: 'auto'

keyboardAnnouncementsUnion—

Name: keyboardAnnouncements
Description: Screen-reader announcements for keyboard drags. Merged over the defaults; omit a callback to keep its default.
Type: | DragKeyboardAnnouncements<TData> | DragKeyboardAnnouncements<undefined> | undefined

keyboardInstructionsstring—

Name: keyboardInstructions
Description: Text for the shared keyboard-drag instructions node, read by a screen reader when the handle is focused. Defaults to the text of the nearest LocalizationProvider.
Type: string | undefined

keyboardMovementUnion—

Name: keyboardMovement
Description: Controls how arrow keys move a keyboard drag. See DragKeyboardMovement. Ignored when keyboardActivation is 'off'.
Type: | DragKeyboardMovement<TData> | DragKeyboardMovement<undefined> | undefined

kind^*Union—

Name: kind
Description: The drag kind created with Draggable.createKind. Drop targets and monitors list accepted kinds in accept. The kind determines the type of payload and source.payload.
Type: DragKind<TData> | DragKind<undefined>

modifiersDragModifiers—

Name: modifiers
Description: Constrains pointer and keyboard movement with one modifier or an array applied in order. See DragModifiers and the exported modifier presets.
Type: DragModifiers | undefined

onBeforeDragStartfunction—

Name: onBeforeDragStart
Description: Event handler called when a drag is about to start, once the activation condition is met and before the preview is built and getPayload runs. Call eventDetails.cancel() to prevent the drag from starting.
Type: | (( context: DragStartContext, eventDetails: BeforeDragStartEventDetails, ) => void) | undefined

onDragfunction—

Name: onDrag
Description: Event handler called as the pointer or keyboard cursor moves, limited to one call per animation frame. Drop target stack changes do not call this handler. Use the drop target’s onDrag for hover behavior.
Type: | (( parameters: DragMoveEvent<TData>, eventDetails: DragMoveEventDetails, ) => void) | (( parameters: DragMoveEvent<undefined>, eventDetails: DragMoveEventDetails, ) => void) | undefined

onDragEndfunction—

Name: onDragEnd
Description: Event handler called once when the drag ends after a drop, outside release, or cancellation. Use it to clean up or revert optimistic state. Commit a drop from onDrop. eventDetails.reason identifies the outcome.
Type: | (( parameters: DragEndEvent<TData>, eventDetails: DragEndEventDetails, ) => void) | (( parameters: DragEndEvent<undefined>, eventDetails: DragEndEventDetails, ) => void) | undefined

onDragStartfunction—

Name: onDragStart
Description: Event handler called once, synchronously when the drag starts. The drag preview has already been resolved by then, so it is safe to measure or restyle the source from here.
Type: | (( parameters: DragStartEvent<TData>, eventDetails: DragStartEventDetails, ) => void) | (( parameters: DragStartEvent<undefined>, eventDetails: DragStartEventDetails, ) => void) | undefined

onDropfunction—

Name: onDrop
Description: Event handler called when the drag is released over an accepting drop target. Commit the move here. dropTarget is never null. A drag that ends another way calls only onDragEnd.
Type: | (( parameters: DragDropEvent<TData>, eventDetails: { reason: 'drop'; event: PointerEvent | KeyboardEvent; }, ) => void) | (( parameters: DragDropEvent<undefined>, eventDetails: { reason: 'drop'; event: PointerEvent | KeyboardEvent; }, ) => void) | undefined

onDropTargetChangefunction—

Name: onDropTargetChange
Description: Event handler called when the active drop targets change, because one was entered or left.
Type: | (( parameters: DropTargetChangeEvent<TData>, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: DropTargetChangeEvent<undefined>, eventDetails: DropTargetChangeEventDetails, ) => void) | undefined

payloadTData—

Name: payload
Description: Static payload data. Function values are preserved without being invoked.
Type: TData | undefined

pointerActivationDragActivationConfig—

Name: pointerActivation
Description: Determines when a pointer press starts a drag. Mouse and pen use a 5px distance by default. Touch uses a 250ms press and hold. Pass one DragActivation for every pointer type or a map with per-type values. See keyboardActivation for keyboard pickup.
Type: DragActivationConfig | undefined

previewKeystring | number—

Name: previewKey
Description: Stable identity used to reconnect a settling cloned preview to this source after it remounts. Use the same key for the same logical item across the move. Static payload identity is used as a fallback when it is referentially stable.
Type: string | number | undefined

finalFocusUniontrue

Name: finalFocus
Description: Determines where focus moves after a keyboard drag. See DragKeyboardFinalFocus for the supported values. A pointer drag never moves focus.
Type: | DragKeyboardFinalFocus<TData> | DragKeyboardFinalFocus<undefined> | undefined
Default: true

disabledbooleanfalse

Name: disabled
Description: Whether to disable dragging. Pointer presses and keyboard events keep their native behavior, and Base UI omits the keyboard-drag accessibility attributes. Use onBeforeDragStart instead when the decision depends on the gesture.
Type: boolean | undefined
Default: false

childrenReact.ReactNode—

Name: children
Type: 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: Draggable.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: Draggable.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: Draggable.Root.State, ) => ReactElement) | undefined

data-dragging

Present on the source element while it is being dragged. A cloned preview never carries this attribute, so a [data-dragging] rule that dims or hides the source leaves the preview fully visible.

data-disabled

Present while the draggable is disabled.

data-displacing

Present while Draggable.Displacement is animating this element being pushed aside by a reorder, paired with the --drag-displacement-x/--drag-displacement-y variables. Use it to apply the displacement transition.

data-drag-mode

The input method driving the drag, either 'pointer' or 'keyboard'. Present on the source alongside data-dragging, and also on the preview.

data-starting-style

Present alongside data-displacing on the first frame of a displacement, while the element should still sit at its old position. Style the displaced state under it, and the transition under data-displacing without it.

data-ending-style

Present on the source after a deliberate release while a clone created by Base UI settles into its final position, including a return after release outside a target. Use it to keep the source styled as a placeholder until the preview’s ending animation finishes.

Attribute	Description	-
`data-dragging`	Present on the source element while it is being dragged. A cloned preview never carries this attribute, so a `[data-dragging]` rule that dims or hides the source leaves the preview fully visible.
`data-disabled`	Present while the draggable is disabled.
`data-displacing`	Present while `Draggable.Displacement` is animating this element being pushed aside by a reorder, paired with the `--drag-displacement-x`/`--drag-displacement-y` variables. Use it to apply the displacement transition.
`data-drag-mode`	The input method driving the drag, either `'pointer'` or `'keyboard'`. Present on the source alongside `data-dragging`, and also on the preview.
`data-starting-style`	Present alongside `data-displacing` on the first frame of a displacement, while the element should still sit at its old position. Style the displaced state under it, and the transition under `data-displacing` without it.
`data-ending-style`	Present on the source after a deliberate release while a clone created by Base UI settles into its final position, including a return after release outside a target. Use it to keep the source styled as a placeholder until the preview’s ending animation finishes.

--drag-displacement-x

The horizontal distance, in pixels, from this element’s new layout position to its previous position. It is calculated as previous minus current, so a row that moved up has a positive value. Present with data-displacing. Apply it under data-starting-style to transition the element to its new position.

--drag-displacement-y

The vertical counterpart of --drag-displacement-x.

CSS Variable	Description	-
`--drag-displacement-x`	The horizontal distance, in pixels, from this element’s new layout position to its previous position. It is calculated as previous minus current, so a row that moved up has a positive value. Present with `data-displacing`. Apply it under `data-starting-style` to transition the element to its new position.
`--drag-displacement-y`	The vertical counterpart of `--drag-displacement-x`.

Draggable.Root.PropsHide

Re-Export of Root props as DraggableRootProps

Draggable.Root.StateHide

type DraggableRootState = {
  /** Whether this element is the one currently being dragged. */
  dragging: boolean;
  /** Whether the draggable is disabled. */
  disabled: boolean;
}

Draggable.Root.PropsWithPayloadHide

type DraggableRootPropsWithPayload<TData> = (
  | { payload: TData; getPayload?: undefined }
  | { payload?: undefined; getPayload: DraggablePayloadGetter<TData> }
) & {
  /**
   * CSS class applied to the element, or a function that
   * returns a class based on the component's state.
   */
  className?: string | ((state: Draggable.Root.State) => string | undefined);
  /**
   * Style applied to the element, or a function that
   * returns a style object based on the component's state.
   */
  style?: React.CSSProperties | ((state: Draggable.Root.State) => React.CSSProperties | undefined);
  /**
   * 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.
   */
  render?: ReactElement | ((props: HTMLProps, state: Draggable.Root.State) => ReactElement);
  /**
   * Human-readable name of this draggable, used by the default screen-reader
   * announcements for keyboard drags. Defaults to a generic "item".
   * For full control over the announcement text, use `keyboardAnnouncements` instead.
   */
  label?: string;
  /**
   * Event handler called as the pointer or keyboard cursor moves, limited to one
   * call per animation frame. Drop target stack changes do not call this handler.
   * Use the drop target's `onDrag` for hover behavior.
   */
  onDrag?: (parameters: DragMoveEvent<TData>, eventDetails: DragMoveEventDetails) => void;
  /**
   * Event handler called once when the drag ends after a drop, outside release, or
   * cancellation. Use it to clean up or revert optimistic state. Commit a drop from
   * `onDrop`. `eventDetails.reason` identifies the outcome.
   */
  onDragEnd?: (parameters: DragEndEvent<TData>, eventDetails: DragEndEventDetails) => void;
  /**
   * Event handler called once, synchronously when the drag starts. The drag preview
   * has already been resolved by then, so it is safe to measure or restyle the
   * source from here.
   */
  onDragStart?: (parameters: DragStartEvent<TData>, eventDetails: DragStartEventDetails) => void;
  /**
   * Event handler called when the drag is released over an accepting drop target.
   * Commit the move here. `dropTarget` is never `null`. A drag that ends another
   * way calls only `onDragEnd`.
   */
  onDrop?: (
    parameters: DragDropEvent<TData>,
    eventDetails: { reason: 'drop'; event: PointerEvent | KeyboardEvent },
  ) => void;
  /**
   * Stable identity used to reconnect a settling cloned preview to this source
   * after it remounts. Use the same key for the same logical item across the move.
   * Static payload identity is used as a fallback when it is referentially stable.
   */
  previewKey?: string | number;
  /**
   * The drag kind created with `Draggable.createKind`. Drop targets and monitors
   * list accepted kinds in `accept`. The kind determines the type of `payload` and
   * `source.payload`.
   */
  kind: DragKind<TData>;
  /**
   * Whether to disable dragging. Pointer presses and keyboard events keep their
   * native behavior, and Base UI omits the keyboard-drag accessibility attributes.
   * Use `onBeforeDragStart` instead when the decision depends on the gesture.
   * @default false
   */
  disabled?: boolean;
  /**
   * Event handler called when a drag is about to start, once the activation condition
   * is met and before the preview is built and `getPayload` runs.
   * Call `eventDetails.cancel()` to prevent the drag from starting.
   */
  onBeforeDragStart?: (
    context: DragStartContext,
    eventDetails: BeforeDragStartEventDetails,
  ) => void;
  /**
   * Determines when a pointer press starts a drag. Mouse and pen use a 5px distance
   * by default. Touch uses a 250ms press and hold. Pass one `DragActivation` for
   * every pointer type or a map with per-type values. See `keyboardActivation` for
   * keyboard pickup.
   */
  pointerActivation?: DragActivationConfig;
  /**
   * Screen-reader announcements for keyboard drags.
   * Merged over the defaults; omit a callback to keep its default.
   */
  keyboardAnnouncements?: DragKeyboardAnnouncements<TData>;
  /**
   * Determines where focus moves after a keyboard drag. See
   * [`DragKeyboardFinalFocus`](#dragkeyboardfinalfocus) for the supported values.
   * A pointer drag never moves focus.
   * @default true
   */
  finalFocus?: DragKeyboardFinalFocus<TData>;
  /**
   * Value for `aria-roledescription` on the drag handle, announcing the
   * element as draggable to screen readers. Defaults to the text of the nearest
   * `LocalizationProvider`.
   */
  ariaRoleDescription?: string;
  /**
   * Text for the shared keyboard-drag instructions node, read by a screen reader when
   * the handle is focused. Defaults to the text of the nearest `LocalizationProvider`.
   */
  keyboardInstructions?: string;
  /**
   * How keyboard dragging is started. See [`DragKeyboardActivation`](#dragkeyboardactivation) for
   * the supported modes.
   * @default 'auto'
   */
  keyboardActivation?: DragKeyboardActivation;
  /**
   * Controls how arrow keys move a keyboard drag. See [`DragKeyboardMovement`](#dragkeyboardmovement).
   * Ignored when `keyboardActivation` is `'off'`.
   */
  keyboardMovement?: DragKeyboardMovement<TData>;
  /**
   * Constrains pointer and keyboard movement with one modifier or an array applied
   * in order. See [`DragModifiers`](#dragmodifiers) and the exported modifier presets.
   */
  modifiers?: DragModifiers;
  /**
   * CSS cursor applied across the document during a pointer drag. The drag preview
   * has `pointer-events: none`, so otherwise the cursor would depend on the element
   * under the pointer. Touch drags ignore this value.
   * Pass `false` to manage the cursor yourself.
   * @default 'grabbing'
   */
  dragCursor?: string | false;
  /**
   * Event handler called when the active drop targets change,
   * because one was entered or left.
   */
  onDropTargetChange?: (
    parameters: DropTargetChangeEvent<TData>,
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  children?: React.ReactNode;
}

Handle

nativeButtonbooleantrue

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

disabledundefined—

Name: disabled
Description: A handle has no independent disabled state. Setting disabled here would disable the button while leaving its root keyboard-draggable. Set disabled on Draggable.Root instead.

This prop is typed as never so passing it causes a type error.
Type: undefined | 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: Draggable.Handle.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: Draggable.Handle.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: Draggable.Handle.State, ) => ReactElement) | undefined

data-disabled

Present while the handle’s Draggable.Root is disabled. A handle follows the disabled state of its root.

Attribute	Description	-
`data-disabled`	Present while the handle’s `Draggable.Root` is disabled. A handle follows the disabled state of its root.

Draggable.Handle.PropsHide

Re-Export of Handle props as DraggableHandleProps

Draggable.Handle.StateHide

type DraggableHandleState = {
  /** Whether the draggable is disabled. */
  disabled: boolean;
}

KeyboardHandle

nativeButtonbooleantrue

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

disabledundefined—

Name: disabled
Description: A handle has no independent disabled state. Set disabled on Draggable.Root instead.
Type: undefined | 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: Draggable.KeyboardHandle.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: Draggable.KeyboardHandle.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: Draggable.KeyboardHandle.State, ) => ReactElement) | undefined

data-disabled

Present while the handle’s Draggable.Root is disabled.

Attribute	Description	-
`data-disabled`	Present while the handle’s `Draggable.Root` is disabled.

Draggable.KeyboardHandle.PropsHide

Re-Export of KeyboardHandle props as DraggableKeyboardHandleProps

Draggable.KeyboardHandle.StateHide

type DraggableKeyboardHandleState = {
  /** Whether the draggable is disabled. */
  disabled: boolean;
}

Preview

kindDragKind<TData>—

Name: kind
Description: The source kind whose payload the render callback accepts.
Type: DragKind<TData> | undefined

modifiersDragModifiers—

Name: modifiers
Description: Constrains the preview without affecting the drag. The resolved drop target and location.current.input remain unchanged. Here the modifier’s point is the preview’s proposed top-left and input is the cursor. Runs on every positioned frame, so keep modifiers cheap.

To constrain the drag itself, use modifiers on Draggable.Root.
Type: DragModifiers | undefined

offsetDragPreviewOffset'source'

Name: offset
Description: Determines where the preview sits relative to the pointer. See DragPreviewOffset for the supported values.
Type: DragPreviewOffset | undefined
Default: 'source'

containerDragPreviewContainer—

Name: container
Description: Determines where the preview is injected in the DOM. Defaults to the source’s own parent, so the app’s CSS still applies to it.

Pass a container to keep structural selectors such as :nth-child and :last-child unchanged, or to keep the preview mounted if the source subtree unmounts. CSS selectors based on the source’s ancestors may no longer match. Draggable.PreviewProvider can set the container for a whole subtree.
Type: DragPreviewContainer | undefined

disabledbooleanfalse

Name: disabled
Description: Whether to hide the preview. The drag continues while no preview is shown.
Type: boolean | undefined
Default: false

children

| React.ReactNode 
|  ((parameters: DragPreviewRenderEvent<TData>) => React.ReactNode) 
|  ((parameters: DragPreviewRenderEvent) => React.ReactNode)

—

Name: children
Description: Preview content, resolved once at drag start with the kind’s payload type.
Type: | React.ReactNode | (( parameters: DragPreviewRenderEvent<TData>, ) => React.ReactNode) | (( parameters: DragPreviewRenderEvent, ) => 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: Draggable.Preview.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: Draggable.Preview.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: Draggable.Preview.State, ) => ReactElement) | undefined

data-drag-mode

The input method driving the drag, either 'pointer' or 'keyboard'. Use it to transition the preview’s translate during keyboard drags without adding a transition to pointer drags.

data-drag-preview

Present on the drag preview element. A cloned preview keeps the source’s classes, so use this attribute to distinguish them in CSS.

data-ending-style

Present on a cloned preview created by Base UI after a deliberate release while it moves to its final position. This also applies when a drag is released outside a target and returns to its source. The clone remains mounted until animations started by this state finish.

Attribute	Description	-
`data-drag-mode`	The input method driving the drag, either `'pointer'` or `'keyboard'`. Use it to transition the preview’s `translate` during keyboard drags without adding a transition to pointer drags.
`data-drag-preview`	Present on the drag preview element. A cloned preview keeps the source’s classes, so use this attribute to distinguish them in CSS.
`data-ending-style`	Present on a cloned preview created by Base UI after a deliberate release while it moves to its final position. This also applies when a drag is released outside a target and returns to its source. The clone remains mounted until animations started by this state finish.

--drag-source-height

The height of the element the drag was lifted from.

--drag-source-width

The width of the element the drag was lifted from.

CSS Variable	Description	-
`--drag-source-height`	The height of the element the drag was lifted from.
`--drag-source-width`	The width of the element the drag was lifted from.

Draggable.Preview.PropsHide

Re-Export of Preview props as DraggablePreviewProps

Draggable.Preview.StateHide

type DraggablePreviewState = {}

ClonedPreview

modifiersDragModifiers—

Name: modifiers
Description: Constrains the preview without affecting the drag. The resolved drop target and location.current.input remain unchanged. Here the modifier’s point is the preview’s proposed top-left and input is the cursor. Runs on every positioned frame, so keep modifiers cheap.

To constrain the drag itself, use modifiers on Draggable.Root.
Type: DragModifiers | undefined

offsetDragPreviewOffset'source'

Name: offset
Description: Determines where the preview sits relative to the pointer. See DragPreviewOffset for the supported values.
Type: DragPreviewOffset | undefined
Default: 'source'

containerDragPreviewContainer—

Name: container
Description: Determines where the preview is injected in the DOM. Defaults to the source’s own parent, so the app’s CSS still applies to it.

Pass a container to keep structural selectors such as :nth-child and :last-child unchanged, or to keep the preview mounted if the source subtree unmounts. CSS selectors based on the source’s ancestors may no longer match. Draggable.PreviewProvider can set the container for a whole subtree.
Type: DragPreviewContainer | undefined

disabledbooleanfalse

Name: disabled
Description: Whether to hide the preview. The drag continues while no preview is shown.
Type: boolean | undefined
Default: false

Draggable.ClonedPreview.PropsHide

Re-Export of ClonedPreview props as DraggableClonedPreviewProps

PreviewProvider

containerDragPreviewContainer—

Name: container
Description: Where to inject the previews of the sources inside this provider, overriding the default of the source’s own parent. A preview’s own container wins over it. A callback resolves it from the source, for example (source) => source.closest('.grid').
Type: DragPreviewContainer | undefined

childrenReact.ReactNode—

Name: children
Description: The part of your app whose custom drag previews render in this provider.
Type: React.ReactNode | undefined

Draggable.PreviewProvider.PropsHide

Re-Export of PreviewProvider props as DraggablePreviewProviderProps

Draggable.PreviewProvider.StateHide

type DraggablePreviewProviderState = {}

restrictToVerticalAxis

Locks the drag to the vertical axis at its initial horizontal position.

Parameters

DragModifierContext

point^*DragPosition

Name: point
Description: The point being constrained, in client coordinates. On Draggable.Root this is the cursor; on a preview part it is the preview’s proposed top-left.
Type: DragPosition

initialPoint^*DragPosition

Name: initialPoint
Description: The same measure when the drag began, the reference an axis lock or grid snaps against.
Type: DragPosition

input^*DragPosition

Name: input
Description: The cursor this frame, in client coordinates. Identical to point on Draggable.Root; on a preview part it stays the cursor while point is the preview’s proposed top-left.
Type: DragPosition

sourceElement^*HTMLElement

Name: sourceElement
Description: The drag source element.
Type: HTMLElement

sourceRect^*DOMRect

Name: sourceRect
Description: The source element’s bounding rect at drag start.
Type: DOMRect

scale^*DragPosition

Name: scale
Description: The scale applied to the source by CSS transform or zoom, measured at drag start across the source and its ancestors.

The value is 1 when the source is not scaled. A rotation alone does not change it. On a zoomable canvas, multiply a distance in canvas coordinates by this value to convert it to client pixels. The snapToGrid preset does this automatically.
Type: DragPosition

previewRect^*DOMRect | null

Name: previewRect
Description: The preview element’s current rect, or null when there is no preview.
Type: DOMRect | null

previewOffset^*DragPosition

Name: previewOffset
Description: The offset from the preview’s top-left to point, so the preview is drawn at point − previewOffset. (0, 0) on a preview part and when there is no preview.
Type: DragPosition

mode^*DragMode

Name: mode
Description: The input method driving the drag.
Type: DragMode

ctrlKey^*boolean

Name: ctrlKey
Description: Whether the Control key was held by the event that produced this move.

During a pointer drag, pressing or releasing a modifier key reapplies the drag modifiers on the next frame. During a keyboard drag, the flags describe each arrow press. Ctrl, Alt, and Meta chords remain available for other shortcuts.

Check mode with these flags because a key may behave differently for pointer and keyboard drags. For example, Shift increases the step used by fixedStepKeyboardMovement.
Type: boolean

shiftKey^*boolean

Name: shiftKey
Description: Whether the Shift key was held by the event that produced this move. See ctrlKey.
Type: boolean

altKey^*boolean

Name: altKey
Description: Whether the Alt key was held by the event that produced this move. See ctrlKey.
Type: boolean

metaKey^*boolean

Name: metaKey
Description: Whether the Meta (Command/Windows) key was held by the event that produced this move. See ctrlKey.
Type: boolean

ownerWindow^*Window

Name: ownerWindow
Description: The document’s window, for viewport-relative modifiers.
Type: Window

Return value

DragPosition

xnumber

Name: x
Type: number

ynumber

Name: y
Type: number

restrictToHorizontalAxis

Locks the drag to the horizontal axis at its initial vertical position.

Parameters

DragModifierContext

point^*DragPosition

Name: point
Description: The point being constrained, in client coordinates. On Draggable.Root this is the cursor; on a preview part it is the preview’s proposed top-left.
Type: DragPosition

initialPoint^*DragPosition

Name: initialPoint
Description: The same measure when the drag began, the reference an axis lock or grid snaps against.
Type: DragPosition

input^*DragPosition

Name: input
Description: The cursor this frame, in client coordinates. Identical to point on Draggable.Root; on a preview part it stays the cursor while point is the preview’s proposed top-left.
Type: DragPosition

sourceElement^*HTMLElement

Name: sourceElement
Description: The drag source element.
Type: HTMLElement

sourceRect^*DOMRect

Name: sourceRect
Description: The source element’s bounding rect at drag start.
Type: DOMRect

scale^*DragPosition

Name: scale
Description: The scale applied to the source by CSS transform or zoom, measured at drag start across the source and its ancestors.

The value is 1 when the source is not scaled. A rotation alone does not change it. On a zoomable canvas, multiply a distance in canvas coordinates by this value to convert it to client pixels. The snapToGrid preset does this automatically.
Type: DragPosition

previewRect^*DOMRect | null

Name: previewRect
Description: The preview element’s current rect, or null when there is no preview.
Type: DOMRect | null

previewOffset^*DragPosition

Name: previewOffset
Description: The offset from the preview’s top-left to point, so the preview is drawn at point − previewOffset. (0, 0) on a preview part and when there is no preview.
Type: DragPosition

mode^*DragMode

Name: mode
Description: The input method driving the drag.
Type: DragMode

ctrlKey^*boolean

Name: ctrlKey
Description: Whether the Control key was held by the event that produced this move.

During a pointer drag, pressing or releasing a modifier key reapplies the drag modifiers on the next frame. During a keyboard drag, the flags describe each arrow press. Ctrl, Alt, and Meta chords remain available for other shortcuts.

Check mode with these flags because a key may behave differently for pointer and keyboard drags. For example, Shift increases the step used by fixedStepKeyboardMovement.
Type: boolean

shiftKey^*boolean

Name: shiftKey
Description: Whether the Shift key was held by the event that produced this move. See ctrlKey.
Type: boolean

altKey^*boolean

Name: altKey
Description: Whether the Alt key was held by the event that produced this move. See ctrlKey.
Type: boolean

metaKey^*boolean

Name: metaKey
Description: Whether the Meta (Command/Windows) key was held by the event that produced this move. See ctrlKey.
Type: boolean

ownerWindow^*Window

Name: ownerWindow
Description: The document’s window, for viewport-relative modifiers.
Type: Window

Return value

DragPosition

xnumber

Name: x
Type: number

ynumber

Name: y
Type: number

restrictToParentElement

Keep the drag within the source element’s parent.

Parameters

DragModifierContext

point^*DragPosition

Name: point
Description: The point being constrained, in client coordinates. On Draggable.Root this is the cursor; on a preview part it is the preview’s proposed top-left.
Type: DragPosition

initialPoint^*DragPosition

Name: initialPoint
Description: The same measure when the drag began, the reference an axis lock or grid snaps against.
Type: DragPosition

input^*DragPosition

Name: input
Description: The cursor this frame, in client coordinates. Identical to point on Draggable.Root; on a preview part it stays the cursor while point is the preview’s proposed top-left.
Type: DragPosition

sourceElement^*HTMLElement

Name: sourceElement
Description: The drag source element.
Type: HTMLElement

sourceRect^*DOMRect

Name: sourceRect
Description: The source element’s bounding rect at drag start.
Type: DOMRect

scale^*DragPosition

Name: scale
Description: The scale applied to the source by CSS transform or zoom, measured at drag start across the source and its ancestors.

The value is 1 when the source is not scaled. A rotation alone does not change it. On a zoomable canvas, multiply a distance in canvas coordinates by this value to convert it to client pixels. The snapToGrid preset does this automatically.
Type: DragPosition

previewRect^*DOMRect | null

Name: previewRect
Description: The preview element’s current rect, or null when there is no preview.
Type: DOMRect | null

previewOffset^*DragPosition

Name: previewOffset
Description: The offset from the preview’s top-left to point, so the preview is drawn at point − previewOffset. (0, 0) on a preview part and when there is no preview.
Type: DragPosition

mode^*DragMode

Name: mode
Description: The input method driving the drag.
Type: DragMode

ctrlKey^*boolean

Name: ctrlKey
Description: Whether the Control key was held by the event that produced this move.

During a pointer drag, pressing or releasing a modifier key reapplies the drag modifiers on the next frame. During a keyboard drag, the flags describe each arrow press. Ctrl, Alt, and Meta chords remain available for other shortcuts.

Check mode with these flags because a key may behave differently for pointer and keyboard drags. For example, Shift increases the step used by fixedStepKeyboardMovement.
Type: boolean

shiftKey^*boolean

Name: shiftKey
Description: Whether the Shift key was held by the event that produced this move. See ctrlKey.
Type: boolean

altKey^*boolean

Name: altKey
Description: Whether the Alt key was held by the event that produced this move. See ctrlKey.
Type: boolean

metaKey^*boolean

Name: metaKey
Description: Whether the Meta (Command/Windows) key was held by the event that produced this move. See ctrlKey.
Type: boolean

ownerWindow^*Window

Name: ownerWindow
Description: The document’s window, for viewport-relative modifiers.
Type: Window

Return value

DragPosition

xnumber

Name: x
Type: number

ynumber

Name: y
Type: number

restrictToElement

Keep the drag within an element’s bounds. Pass the element, a ref object, or a function returning it. The rect is read on every constrained move, so a container that scrolls or resizes between moves is tracked.

Parameters

element^*DragElementReference—

Name: element
Type: DragElementReference

Return value

DragModifier

restrictToWindowEdges

Keep the drag within the viewport.

Parameters

DragModifierContext

point^*DragPosition

Name: point
Description: The point being constrained, in client coordinates. On Draggable.Root this is the cursor; on a preview part it is the preview’s proposed top-left.
Type: DragPosition

initialPoint^*DragPosition

Name: initialPoint
Description: The same measure when the drag began, the reference an axis lock or grid snaps against.
Type: DragPosition

input^*DragPosition

Name: input
Description: The cursor this frame, in client coordinates. Identical to point on Draggable.Root; on a preview part it stays the cursor while point is the preview’s proposed top-left.
Type: DragPosition

sourceElement^*HTMLElement

Name: sourceElement
Description: The drag source element.
Type: HTMLElement

sourceRect^*DOMRect

Name: sourceRect
Description: The source element’s bounding rect at drag start.
Type: DOMRect

scale^*DragPosition

Name: scale
Description: The scale applied to the source by CSS transform or zoom, measured at drag start across the source and its ancestors.

The value is 1 when the source is not scaled. A rotation alone does not change it. On a zoomable canvas, multiply a distance in canvas coordinates by this value to convert it to client pixels. The snapToGrid preset does this automatically.
Type: DragPosition

previewRect^*DOMRect | null

Name: previewRect
Description: The preview element’s current rect, or null when there is no preview.
Type: DOMRect | null

previewOffset^*DragPosition

Name: previewOffset
Description: The offset from the preview’s top-left to point, so the preview is drawn at point − previewOffset. (0, 0) on a preview part and when there is no preview.
Type: DragPosition

mode^*DragMode

Name: mode
Description: The input method driving the drag.
Type: DragMode

ctrlKey^*boolean

Name: ctrlKey
Description: Whether the Control key was held by the event that produced this move.

During a pointer drag, pressing or releasing a modifier key reapplies the drag modifiers on the next frame. During a keyboard drag, the flags describe each arrow press. Ctrl, Alt, and Meta chords remain available for other shortcuts.

Check mode with these flags because a key may behave differently for pointer and keyboard drags. For example, Shift increases the step used by fixedStepKeyboardMovement.
Type: boolean

shiftKey^*boolean

Name: shiftKey
Description: Whether the Shift key was held by the event that produced this move. See ctrlKey.
Type: boolean

altKey^*boolean

Name: altKey
Description: Whether the Alt key was held by the event that produced this move. See ctrlKey.
Type: boolean

metaKey^*boolean

Name: metaKey
Description: Whether the Meta (Command/Windows) key was held by the event that produced this move. See ctrlKey.
Type: boolean

ownerWindow^*Window

Name: ownerWindow
Description: The document’s window, for viewport-relative modifiers.
Type: Window

Return value

DragPosition

xnumber

Name: x
Type: number

ynumber

Name: y
Type: number

snapToGrid

Snap the drag to a grid, anchored at the point where the drag began. Pass a single number for a square grid or { x, y } for a rectangular one. A non-positive step leaves that axis unsnapped.

The step uses the source’s coordinate system. For example, snapToGrid(20) still snaps to a 20-unit grid when the canvas is zoomed to 70%.

Parameters

size^*Union—

Name: size
Type: number | { x: number; y: number }

Return value

DragModifier

targetsOnlyKeyboardMovement

A keyboardMovement preset that moves only between accepting drop targets. Each arrow press moves to the nearest target in that direction. If no target is available, nothing moves. Use it for sortable lists and boards where empty space is not a valid drop position.

direction^*DragPosition—

Name: direction
Description: Unit vector for key. ArrowUp is { x: 0, y: -1 }.
Type: DragPosition

event^*KeyboardEvent—

Name: event
Description: The native keydown event.
Type: KeyboardEvent

findTarget^*function—

Name: findTarget
Description: Runs the default directional collision and returns the nearest accepting drop target ahead of the cursor, or null when none lies ahead. Pass key to look in another direction than the pressed one, and from to look from another origin than the current cursor.
Type: (options?: { key?: DragKeyboardArrowKey; from?: DragPosition; }) => Element | null

getTargets^*function—

Name: getTargets
Description: Returns every drop target accepting this drag, with freshly measured rects.
Type: () => DragKeyboardMoveTarget[]

key^*DragKeyboardArrowKey—

Name: key
Description: The arrow key pressed.
Type: DragKeyboardArrowKey

location^*DragLocationHistory—

Name: location
Description: Where the drag started and where it is now, including its drop targets.
Type: DragLocationHistory

position^*DragPosition—

Name: position
Description: The virtual cursor before this press, in client coordinates.
Type: DragPosition

shiftKey^*boolean—

Name: shiftKey
Description: Whether the Shift key was held. No multiplier is applied to a resolver result.
Type: boolean

source^*DragSource—

Name: source
Description: The drag source being moved.
Type: DragSource

suggestion^*DragKeyboardMoveSuggestion—

Name: suggestion
Description: What the default behavior would do for this press.
Type: DragKeyboardMoveSuggestion

target^*DropTargetRecord | null—

Name: target
Description: The innermost drop target currently under the virtual cursor, or null.
Type: DropTargetRecord | null

fixedStepKeyboardMovement

A keyboardMovement preset that moves by a fixed step without finding a drop target.

Use it on a canvas where every point is valid. The default target search could otherwise move the source across the canvas when a drop target is registered.

step uses the source’s coordinate system, so an ancestor scale() does not change the distance on a zoomable canvas. Holding Shift moves four times as far.

<Draggable.Root keyboardMovement={Draggable.fixedStepKeyboardMovement(20)} />

Parameters

step^*Union—

Name: step
Type: number | { x: number; y: number }

Return value

DragKeyboardMovement

DragModifier

Modifies the drag position. Use it to lock an axis, snap to a grid, or constrain the drag to an element or window. It receives the proposed point and returns the point to use.

Prebuilt modifiers: restrictToVerticalAxis, restrictToHorizontalAxis, restrictToWindowEdges, restrictToParentElement, restrictToElement, snapToGrid.

Parameters

DragModifierContext

point^*DragPosition

Name: point
Description: The point being constrained, in client coordinates. On Draggable.Root this is the cursor; on a preview part it is the preview’s proposed top-left.
Type: DragPosition

initialPoint^*DragPosition

Name: initialPoint
Description: The same measure when the drag began, the reference an axis lock or grid snaps against.
Type: DragPosition

input^*DragPosition

Name: input
Description: The cursor this frame, in client coordinates. Identical to point on Draggable.Root; on a preview part it stays the cursor while point is the preview’s proposed top-left.
Type: DragPosition

sourceElement^*HTMLElement

Name: sourceElement
Description: The drag source element.
Type: HTMLElement

sourceRect^*DOMRect

Name: sourceRect
Description: The source element’s bounding rect at drag start.
Type: DOMRect

scale^*DragPosition

Name: scale
Description: The scale applied to the source by CSS transform or zoom, measured at drag start across the source and its ancestors.

The value is 1 when the source is not scaled. A rotation alone does not change it. On a zoomable canvas, multiply a distance in canvas coordinates by this value to convert it to client pixels. The snapToGrid preset does this automatically.
Type: DragPosition

previewRect^*DOMRect | null

Name: previewRect
Description: The preview element’s current rect, or null when there is no preview.
Type: DOMRect | null

previewOffset^*DragPosition

Name: previewOffset
Description: The offset from the preview’s top-left to point, so the preview is drawn at point − previewOffset. (0, 0) on a preview part and when there is no preview.
Type: DragPosition

mode^*DragMode

Name: mode
Description: The input method driving the drag.
Type: DragMode

ctrlKey^*boolean

Name: ctrlKey
Description: Whether the Control key was held by the event that produced this move.

During a pointer drag, pressing or releasing a modifier key reapplies the drag modifiers on the next frame. During a keyboard drag, the flags describe each arrow press. Ctrl, Alt, and Meta chords remain available for other shortcuts.

Check mode with these flags because a key may behave differently for pointer and keyboard drags. For example, Shift increases the step used by fixedStepKeyboardMovement.
Type: boolean

shiftKey^*boolean

Name: shiftKey
Description: Whether the Shift key was held by the event that produced this move. See ctrlKey.
Type: boolean

altKey^*boolean

Name: altKey
Description: Whether the Alt key was held by the event that produced this move. See ctrlKey.
Type: boolean

metaKey^*boolean

Name: metaKey
Description: Whether the Meta (Command/Windows) key was held by the event that produced this move. See ctrlKey.
Type: boolean

ownerWindow^*Window

Name: ownerWindow
Description: The document’s window, for viewport-relative modifiers.
Type: Window

Return value

DragPosition

xnumber

Name: x
Type: number

ynumber

Name: y
Type: number

DragKeyboardMovement

Controls how arrow keys move a keyboard drag. Called on every arrow press with the press, the drag context, and the suggested move.

direction^*DragPosition—

Name: direction
Description: Unit vector for key. ArrowUp is { x: 0, y: -1 }.
Type: DragPosition

event^*KeyboardEvent—

Name: event
Description: The native keydown event.
Type: KeyboardEvent

findTarget^*function—

Name: findTarget
Description: Runs the default directional collision and returns the nearest accepting drop target ahead of the cursor, or null when none lies ahead. Pass key to look in another direction than the pressed one, and from to look from another origin than the current cursor.
Type: (options?: { key?: DragKeyboardArrowKey; from?: DragPosition; }) => Element | null

getTargets^*function—

Name: getTargets
Description: Returns every drop target accepting this drag, with freshly measured rects.
Type: () => DragKeyboardMoveTarget[]

key^*DragKeyboardArrowKey—

Name: key
Description: The arrow key pressed.
Type: DragKeyboardArrowKey

location^*DragLocationHistory—

Name: location
Description: Where the drag started and where it is now, including its drop targets.
Type: DragLocationHistory

position^*DragPosition—

Name: position
Description: The virtual cursor before this press, in client coordinates.
Type: DragPosition

shiftKey^*boolean—

Name: shiftKey
Description: Whether the Shift key was held. No multiplier is applied to a resolver result.
Type: boolean

source^*DragSource<TSourceData>—

Name: source
Description: The drag source being moved.
Type: DragSource<TSourceData>

suggestion^*DragKeyboardMoveSuggestion—

Name: suggestion
Description: What the default behavior would do for this press.
Type: DragKeyboardMoveSuggestion

target^*DropTargetRecord | null—

Name: target
Description: The innermost drop target currently under the virtual cursor, or null.
Type: DropTargetRecord | null

createKind

Creates a drag kind with a unique runtime identity. Declare it once and share the returned value with each draggable, drop target, monitor, and auto-scroller that participates in the interaction. The optional name is only a debugging aid; separately created kinds do not match.

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

createGlobalKind

Creates a globally interned drag kind for integrations where independently evaluated bundles must match without sharing the same kind value.

const card = Draggable.createGlobalKind<Card>('myapp/card');

The key is the runtime identity, so every call with the same key matches, including calls made by another copy of the bundle. It must be namespaced (for example, 'myapp/card') because using the same key with incompatible payload types bypasses TypeScript and causes the integrations to exchange the wrong payload at runtime. Prefer createKind when the kind value can be shared directly.

Parameters

key^*string—

Name: key
Description: A namespaced global key such as 'myapp/card'.
Type: string

Return value

DragKind

namestring

Name: name
Description: The name or global key used to create this kind. This is not an accessible name. Use label on a draggable or drop target instead.
Type: string

idsymbol

Name: id
Description: The kind’s runtime identity. createKind creates a fresh symbol for each call; createGlobalKind interns it on the namespaced key.
Type: symbol

matchesmatches

Name: matches
Description: Whether this drag source is of this kind, narrowing its payload to TPayload.
Type: (type matches = | ((source: { element: HTMLElement; label: string | undefined; kind: symbol; dragHandle: Element | null; payload: unknown; }) => boolean) | ((target: { element: Element; label: string | undefined; kind: symbol | undefined; payload: unknown; getLocalPoint: unknown; getSnappedLocalPoint: unknown; }) => boolean))

useActiveDrag

Pass one kind or an array of kinds to accept. Other drags return null, and accept determines the type of source.payload.

Usage

const anyDrag = Draggable.useActiveDrag();
const cardDrag = Draggable.useActiveDrag(card);

Subscribes to the drag currently in progress, and returns its source, or null if there is none. Observes every drag, regardless of which element started it.

Pass one kind or an array of kinds to accept to observe only matching drags. Other drags return null, and accept determines the source payload type.

Parameters

acceptDragKind | DragKind[]—

Name: accept
Type: DragKind | DragKind[] | undefined

Return value

UseDraggableActiveDragReturnValue<TPayload | unknown>

Draggable.useActiveDrag.ReturnValueHide

type DraggableuseActiveDragReturnValue<TData = unknown> = DragSource<TData> | null

BaseDragEventHide

type BaseDragEvent<TSourceData = unknown> = {
  location: DragLocationHistory;
  source: DragSource<TSourceData>;
  /**
   * The input method driving the drag.
   * This is the reliable way to detect a keyboard drag, as
   * `location.current.input.pointerType` is `null` for those.
   */
  mode: DragMode;
}

BeforeDragStartEventDetailsHide

type BeforeDragStartEventDetails = (
  { reason: 'pointer'; event: PointerEvent } | { reason: 'keyboard'; event: KeyboardEvent }
) & {
  /** Prevents the drag from starting. */
  cancel: () => void;
  /** Allows the native event to propagate when Base UI would stop it. */
  allowPropagation: () => void;
  /** Whether `cancel` has been called. */
  isCanceled: boolean;
  /** Whether `allowPropagation` has been called. */
  isPropagationAllowed: boolean;
  /** The element that initiated the pickup, when available. */
  trigger: Element | undefined;
}

DragAcceptHide

type DragAccept<TPayload> = DragKind<TPayload> | DragKind<TPayload>[]

DragActivationHide

type DragActivation =
  | { type: 'immediate' }
  | { type: 'distance'; distance: number }
  | { type: 'press-hold'; delay: number; tolerance?: number }

DragActivationConfigHide

type DragActivationConfig = DragActivation | Partial<Record<DragPointerType, DragActivation>>

DragCanceledReasonHide

type DragCanceledReason =
  | 'escape-key'
  | 'tab-key'
  | 'pointer-down'
  | 'focus-out'
  | 'imperative-action'
  | 'window-blur'
  | 'page-hidden'
  | 'pointer-canceled'
  | 'capture-lost'
  | 'missed-release'
  | 'document-detached'
  | 'handler-error'

DragCompletedReasonHide

type DragCompletedReason = 'drop' | 'outside-release'

DragDropEventHide

type DragDropEvent<TSourceData = unknown> = {
  location: DragLocationHistory;
  source: DragSource<TSourceData>;
  /**
   * The input method driving the drag.
   * This is the reliable way to detect a keyboard drag, as
   * `location.current.input.pointerType` is `null` for those.
   */
  mode: DragMode;
  dropTarget: DropTargetRecord;
}

DragDropEventDetailsHide

type DragDropEventDetails = {
  /** Why the event fired. */
  reason: 'drop';
  /**
   * The native event behind the dispatch. Programmatic and lifecycle-only
   * reasons carry a generic `Event` placeholder.
   */
  event: PointerEvent | KeyboardEvent;
}

DragDropReasonHide

type DragDropReason = 'drop'

DragElementReferenceHide

type DragElementReference =
  HTMLElement | { current: HTMLElement | null } | (() => HTMLElement | null | undefined)

DragEndEventHide

type DragEndEvent<TSourceData = unknown> = {
  location: DragLocationHistory;
  source: DragSource<TSourceData>;
  /**
   * The input method driving the drag.
   * This is the reliable way to detect a keyboard drag, as
   * `location.current.input.pointerType` is `null` for those.
   */
  mode: DragMode;
  /**
   * Whether the drag was aborted instead of released by the user.
   * A drag released outside of any drop target is not canceled; read `dropTarget` for that,
   * or `eventDetails.reason` for the exact outcome.
   */
  canceled: boolean;
  /**
   * The innermost drop target the release landed on, or `null` when the release was
   * over no target or the drag was canceled.
   */
  dropTarget: DropTargetRecord | null;
}

DragEndEventDetailsHide

type DragEndEventDetails =
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | KeyboardEvent }
  | { reason: 'outside-release'; event: PointerEvent | KeyboardEvent }
  | { reason: 'pointer-down'; event: PointerEvent }
  | { reason: 'focus-out'; event: FocusEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'window-blur'; event: FocusEvent }
  | { reason: 'page-hidden'; event: Event }
  | { reason: 'pointer-canceled'; event: PointerEvent }
  | { reason: 'capture-lost'; event: PointerEvent }
  | { reason: 'missed-release'; event: PointerEvent }
  | { reason: 'document-detached'; event: Event }
  | { reason: 'handler-error'; event: Event }

DragEndReasonHide

type DragEndReason = DragCompletedReason | DragCanceledReason

DragEventDetailsHide

type DragEventDetails<TReason extends string> = {
  /** Why the event fired. */
  reason: TReason;
  /**
   * The native event behind the dispatch. Programmatic and lifecycle-only
   * reasons carry a generic `Event` placeholder.
   */
  event: PointerEvent | KeyboardEvent | FocusEvent | Event;
}

DragEventDetailsMapHide

type DragEventDetailsMap = {
  onDragStart: DragStartEventDetails;
  onDrag: DragMoveEventDetails;
  onDropTargetChange: DropTargetChangeEventDetails;
  onDragEnter: DropTargetChangeEventDetails;
  onDragLeave: DropTargetChangeEventDetails;
  onDrop: DragDropEventDetails;
  onDragEnd: DragEndEventDetails;
}

DragEventMapHide

type DragEventMap<TSourceData = unknown> = {
  onDragStart: DragStartEvent<TSourceData>;
  onDrag: DragMoveEvent<TSourceData>;
  onDropTargetChange: DropTargetChangeEvent<TSourceData>;
  onDragEnter: BaseDragEvent<TSourceData>;
  onDragLeave: BaseDragEvent<TSourceData>;
  onDrop: DragDropEvent<TSourceData>;
  onDragEnd: DragEndEvent<TSourceData>;
}

Draggable.anyKindHide

type DraggableanyKind = {
  /**
   * The name or global key used to create this kind. This is not an accessible
   * name. Use `label` on a draggable or drop target instead.
   */
  name: string;
  /**
   * The kind's runtime identity. `createKind` creates a fresh symbol for each call;
   * `createGlobalKind` interns it on the namespaced key.
   */
  id: symbol;
  /** Whether this drag source is of this kind, narrowing its `payload` to `TPayload`. */
  matches: (type matches =
  | ((source: {
      element: HTMLElement;
      label: string | undefined;
      kind: symbol;
      dragHandle: Element | null;
      payload: unknown;
    }) => boolean)
  | ((target: {
      element: Element;
      label: string | undefined;
      kind: symbol | undefined;
      payload: unknown;
      getLocalPoint: unknown;
      getSnappedLocalPoint: unknown;
    }) => boolean));
}

DraggablePayloadHide

type DraggablePayload = TData

DraggablePreviewTypedPropsHide

type DraggablePreviewTypedProps<TData> = {
  /**
   * CSS class applied to the element, or a function that
   * returns a class based on the component's state.
   */
  className?: string | ((state: Draggable.Preview.State) => string | undefined);
  /**
   * Style applied to the element, or a function that
   * returns a style object based on the component's state.
   */
  style?:
    React.CSSProperties | ((state: Draggable.Preview.State) => React.CSSProperties | undefined);
  /**
   * 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.
   */
  render?: ReactElement | ((props: HTMLProps, state: Draggable.Preview.State) => ReactElement);
  /**
   * Whether to hide the preview. The drag continues while no preview is shown.
   * @default false
   */
  disabled?: boolean;
  /**
   * Constrains the preview without affecting the drag. The resolved drop target and
   * `location.current.input` remain unchanged.
   * Here the modifier's `point` is the preview's proposed top-left and `input` is the
   * cursor. Runs on every positioned frame, so keep modifiers cheap.
   *
   * To constrain the drag itself, use `modifiers` on `Draggable.Root`.
   */
  modifiers?: DragModifiers;
  /**
   * Determines where the preview sits relative to the pointer. See
   * [`DragPreviewOffset`](#dragpreviewoffset) for the supported values.
   * @default 'source'
   */
  offset?: DragPreviewOffset;
  /**
   * Determines where the preview is injected in the DOM.
   * Defaults to the source's own parent, so the app's CSS still applies to it.
   *
   * Pass a container to keep structural selectors such as `:nth-child` and
   * `:last-child` unchanged, or to keep the preview mounted if the source subtree
   * unmounts. CSS selectors based on the source's ancestors may no longer match.
   * `Draggable.PreviewProvider` can set the container for a whole subtree.
   */
  container?: DragPreviewContainer;
  /** The source kind whose payload the render callback accepts. */
  kind: DragKind<TData>;
  /** Preview content, resolved once at drag start with the kind's payload type. */
  children?: React.ReactNode | ((parameters: DragPreviewRenderEvent<TData>) => React.ReactNode);
}

DragHandleHide

type DragHandle = Element | { current: Element | null } | (() => Element | null | undefined)

DragInputHide

type DragInput = {
  /**
   * `MouseEvent.button` semantics: 0 = primary, 1 = middle, 2 = secondary.
   * Move-derived events (`onDrag`, `onDropTargetChange`) carry `-1`, as no button changed.
   * Read `buttons` for what is held mid-drag.
   */
  button: number;
  /** `MouseEvent.buttons` bitmask. */
  buttons: number;
  /** Pointer X relative to the viewport, in CSS pixels. */
  clientX: number;
  /** Pointer Y relative to the viewport, in CSS pixels. */
  clientY: number;
  /** Pointer X relative to the document, in CSS pixels (includes scroll). */
  pageX: number;
  /** Pointer Y relative to the document, in CSS pixels (includes scroll). */
  pageY: number;
  /**
   * The pointer device that produced this input, or `null` for a keyboard drag.
   * Read the event's `mode` to detect a keyboard drag.
   */
  pointerType: DragPointerType | null;
  /** Whether the Control key was held. */
  ctrlKey: boolean;
  /** Whether the Shift key was held. */
  shiftKey: boolean;
  /** Whether the Alt key was held. */
  altKey: boolean;
  /** Whether the Meta (Command/Windows) key was held. */
  metaKey: boolean;
}

DragKeyboardActivationHide

type DragKeyboardActivation = 'auto' | 'manual' | 'off'

DragKeyboardAnnouncementParametersHide

type DragKeyboardAnnouncementParameters<TSourceData = unknown> = {
  /** The drag source being announced. */
  source: DragSource<TSourceData>;
  /** Where the drag started and where it is now, including its drop targets. */
  location: DragLocationHistory;
}

DragKeyboardAnnouncementsHide

type DragKeyboardAnnouncements<TSourceData = unknown> = {
  /** Announced when the item is picked up. */
  pickedUp?: (parameters: DragKeyboardAnnouncementParameters<TSourceData>) => string | null;
  /** Announced, debounced, as the item moves. */
  moved?: (parameters: DragKeyboardAnnouncementParameters<TSourceData>) => string | null;
  /**
   * Announced when the item is released with Space or Enter, whether or not it
   * landed on a drop target.
   */
  dropped?: (parameters: DragKeyboardAnnouncementParameters<TSourceData>) => string | null;
  /** Announced when the drag is canceled with Escape, Tab, or a blur. */
  canceled?: (parameters: DragKeyboardAnnouncementParameters<TSourceData>) => string | null;
  /** Announced when an arrow press moves nowhere. Silent by default. */
  reachedEdge?: (parameters: DragKeyboardAnnouncementParameters<TSourceData>) => string | null;
}

DragKeyboardArrowKeyHide

type DragKeyboardArrowKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight'

DragKeyboardFinalFocusHide

type DragKeyboardFinalFocus<TSourceData = unknown> =
  | boolean
  | { current: HTMLElement | null }
  | ((
      parameters: DragKeyboardFinalFocusParameters<TSourceData>,
    ) => boolean | void | HTMLElement | null)

DragKeyboardFinalFocusParametersHide

type DragKeyboardFinalFocusParameters<TSourceData = unknown> = {
  /** The drag source whose keyboard drag just ended. */
  source: DragSource<TSourceData>;
  /** The final location snapshot, captured before teardown. */
  location: DragLocationHistory;
  /** Whether the drag was aborted instead of released by the user. */
  canceled: boolean;
  /**
   * The innermost drop target the release landed on, or `null` when the release was
   * over no target or the drag was canceled.
   */
  dropTarget: DropTargetRecord | null;
}

DragKeyboardMoveDetailsHide

type DragKeyboardMoveDetails<TSourceData = unknown> = {
  /** The arrow key pressed. */
  key: DragKeyboardArrowKey;
  /** Unit vector for `key`. `ArrowUp` is `{ x: 0, y: -1 }`. */
  direction: DragPosition;
  /** Whether the Shift key was held. No multiplier is applied to a resolver result. */
  shiftKey: boolean;
  /** The native `keydown` event. */
  event: KeyboardEvent;
  /** The virtual cursor before this press, in client coordinates. */
  position: DragPosition;
  /** The drag source being moved. */
  source: DragSource<TSourceData>;
  /** The innermost drop target currently under the virtual cursor, or `null`. */
  target: DropTargetRecord | null;
  /** Where the drag started and where it is now, including its drop targets. */
  location: DragLocationHistory;
  /** What the default behavior would do for this press. */
  suggestion: DragKeyboardMoveSuggestion;
  /**
   * Runs the default directional collision and returns the nearest accepting drop
   * target ahead of the cursor, or `null` when none lies ahead. Pass `key` to look in
   * another direction than the pressed one, and `from` to look from another origin
   * than the current cursor.
   */
  findTarget: (options?: { key?: DragKeyboardArrowKey; from?: DragPosition }) => Element | null;
  /** Returns every drop target accepting this drag, with freshly measured rects. */
  getTargets: () => DragKeyboardMoveTarget[];
}

DragKeyboardMoveResultHide

type DragKeyboardMoveResult = DragPosition | Element | DragKeyboardMoveSuggestion | false | null

DragKeyboardMoveSuggestionHide

type DragKeyboardMoveSuggestion =
  | { type: 'target'; element: Element; position: DragPosition }
  | { type: 'step'; position: DragPosition }

DragKeyboardMoveTargetHide

type DragKeyboardMoveTarget = {
  /** The drop target element. */
  element: Element;
  /** The element's bounding rect, measured when `getTargets` was called. */
  rect: DOMRect;
  /** The resolved drop target record. */
  record: DropTargetRecord;
}

DragKindHide

type DragKind<TPayload = unknown> = {
  /**
   * The name or global key used to create this kind. This is not an accessible
   * name. Use `label` on a draggable or drop target instead.
   */
  name: string;
  /**
   * The kind's runtime identity. `createKind` creates a fresh symbol for each call;
   * `createGlobalKind` interns it on the namespaced key.
   */
  id: symbol;
  /** Whether this drag source is of this kind, narrowing its `payload` to `TPayload`. */
  matches: (type matches =
  | ((source: {
      element: HTMLElement;
      label: string | undefined;
      kind: symbol;
      dragHandle: Element | null;
      payload: unknown;
    }) => boolean)
  | ((target: {
      element: Element;
      label: string | undefined;
      kind: symbol | undefined;
      payload: unknown;
      getLocalPoint: unknown;
      getSnappedLocalPoint: unknown;
    }) => boolean));
}

DragLocalPointHide

type DragLocalPoint = { x: number; y: number }

DragLocationHide

type DragLocation = {
  input: DragInput;
  /** The active drop targets, innermost first. */
  dropTargets: DropTargetRecord[];
}

DragLocationHistoryHide

type DragLocationHistory = {
  /** The location when the drag began. */
  initial: DragLocation;
  /** The location at the moment this event fires. */
  current: DragLocation;
  /**
   * The location at the prior event. On the first event of a drag it holds the
   * pickup input and no drop targets, so a `current` vs `previous` diff reads as
   * no movement rather than a jump.
   */
  previous: DragLocation;
}

DragModeHide

type DragMode = 'pointer' | 'keyboard'

DragModifierContextHide

type DragModifierContext = {
  /**
   * The point being constrained, in client coordinates. On `Draggable.Root` this is
   * the cursor; on a preview part it is the preview's proposed top-left.
   */
  point: DragPosition;
  /** The same measure when the drag began, the reference an axis lock or grid snaps against. */
  initialPoint: DragPosition;
  /**
   * The cursor this frame, in client coordinates. Identical to `point` on
   * `Draggable.Root`; on a preview part it stays the cursor while `point` is the
   * preview's proposed top-left.
   */
  input: DragPosition;
  /** The drag source element. */
  sourceElement: HTMLElement;
  /** The source element's bounding rect at drag start. */
  sourceRect: DOMRect;
  /**
   * The scale applied to the source by CSS `transform` or `zoom`, measured at drag
   * start across the source and its ancestors.
   *
   * The value is `1` when the source is not scaled. A rotation alone does not change
   * it. On a zoomable canvas, multiply a distance in canvas coordinates by this value
   * to convert it to client pixels. The `snapToGrid` preset does this automatically.
   */
  scale: DragPosition;
  /** The preview element's current rect, or `null` when there is no preview. */
  previewRect: DOMRect | null;
  /**
   * The offset from the preview's top-left to `point`, so the preview is drawn at
   * `point − previewOffset`. `(0, 0)` on a preview part and when there is no preview.
   */
  previewOffset: DragPosition;
  /** The input method driving the drag. */
  mode: DragMode;
  /**
   * Whether the Control key was held by the event that produced this move.
   *
   * During a pointer drag, pressing or releasing a modifier key reapplies the drag
   * modifiers on the next frame. During a keyboard drag, the flags describe each
   * arrow press. Ctrl, Alt, and Meta chords remain available for other shortcuts.
   *
   * Check `mode` with these flags because a key may behave differently for pointer
   * and keyboard drags. For example, Shift increases the step used by
   * `fixedStepKeyboardMovement`.
   */
  ctrlKey: boolean;
  /** Whether the Shift key was held by the event that produced this move. See `ctrlKey`. */
  shiftKey: boolean;
  /** Whether the Alt key was held by the event that produced this move. See `ctrlKey`. */
  altKey: boolean;
  /**
   * Whether the Meta (Command/Windows) key was held by the event that produced this move.
   * See `ctrlKey`.
   */
  metaKey: boolean;
  /** The document's window, for viewport-relative modifiers. */
  ownerWindow: Window;
}

DragModifiersHide

type DragModifiers = DragModifier | (false | DragModifier | null | undefined)[]

DragMoveEventHide

type DragMoveEvent<TSourceData = unknown> = {
  location: DragLocationHistory;
  source: DragSource<TSourceData>;
  /**
   * The input method driving the drag.
   * This is the reliable way to detect a keyboard drag, as
   * `location.current.input.pointerType` is `null` for those.
   */
  mode: DragMode;
}

DragMoveEventDetailsHide

type DragMoveEventDetails =
  { reason: 'pointer'; event: PointerEvent } | { reason: 'keyboard'; event: KeyboardEvent }

DragPointerTypeHide

type DragPointerType = 'mouse' | 'pen' | 'touch'

DragPositionHide

type DragPosition = { x: number; y: number }

DragPreviewContainerHide

type DragPreviewContainer =
  | HTMLElement
  | { current: HTMLElement | null }
  | ((source: HTMLElement) => HTMLElement | null | undefined)

DragPreviewOffsetHide

type DragPreviewOffset =
  DragPosition | 'source' | 'pointer' | ((parameters: DragPreviewOffsetParameters) => DragPosition)

DragPreviewOffsetParametersHide

type DragPreviewOffsetParameters = {
  /** The preview element, after its content has rendered, so it has a size. */
  container: HTMLElement;
  /** The drag source element's bounding rect at drag start, in client coordinates. */
  sourceRect: DOMRect;
  /** Pointer state at drag start. */
  input: DragInput;
}

DragPreviewParametersHide

type DragPreviewParameters<TSourceData = unknown> = {
  /**
   * Renders the preview content, replacing the default clone of the source.
   * Return `null` or `false` to show no preview for this drag.
   */
  render?: (parameters: DragPreviewRenderEvent<TSourceData>) => React.ReactNode;
  /**
   * Determines where the preview sits relative to the pointer. See
   * [`DragPreviewOffset`](#dragpreviewoffset) for the supported values.
   * @default 'source'
   */
  offset?: DragPreviewOffset;
  /**
   * Constrains the preview without affecting the drag. The resolved drop target and
   * `location.current.input` remain unchanged.
   * Here the modifier's `point` is the preview's proposed top-left and `input` is the
   * cursor. Runs on every positioned frame, so keep modifiers cheap.
   *
   * To constrain the drag itself, use `modifiers` on `Draggable.Root`.
   */
  modifiers?: DragModifiers;
  /**
   * Whether to hide the preview. The drag continues while no preview is shown.
   * @default false
   */
  disabled?: boolean;
  /**
   * Determines where the preview is injected in the DOM.
   * Defaults to the source's own parent, so the app's CSS still applies to it.
   *
   * Pass a container to keep structural selectors such as `:nth-child` and
   * `:last-child` unchanged, or to keep the preview mounted if the source subtree
   * unmounts. CSS selectors based on the source's ancestors may no longer match.
   * `Draggable.PreviewProvider` can set the container for a whole subtree.
   */
  container?: DragPreviewContainer;
}

DragPreviewRenderEventHide

type DragPreviewRenderEvent<TSourceData = unknown> = {
  location: DragLocationHistory;
  source: DragSource<TSourceData>;
  /**
   * The input method driving the drag.
   * This is the reliable way to detect a keyboard drag, as
   * `location.current.input.pointerType` is `null` for those.
   */
  mode: DragMode;
}

DragPreviewSettingsHide

type DragPreviewSettings = {
  /**
   * Determines where the preview sits relative to the pointer. See
   * [`DragPreviewOffset`](#dragpreviewoffset) for the supported values.
   * @default 'source'
   */
  offset?: DragPreviewOffset;
  /**
   * Constrains the preview without affecting the drag. The resolved drop target and
   * `location.current.input` remain unchanged.
   * Here the modifier's `point` is the preview's proposed top-left and `input` is the
   * cursor. Runs on every positioned frame, so keep modifiers cheap.
   *
   * To constrain the drag itself, use `modifiers` on `Draggable.Root`.
   */
  modifiers?: DragModifiers;
  /**
   * Whether to hide the preview. The drag continues while no preview is shown.
   * @default false
   */
  disabled?: boolean;
  /**
   * Determines where the preview is injected in the DOM.
   * Defaults to the source's own parent, so the app's CSS still applies to it.
   *
   * Pass a container to keep structural selectors such as `:nth-child` and
   * `:last-child` unchanged, or to keep the preview mounted if the source subtree
   * unmounts. CSS selectors based on the source's ancestors may no longer match.
   * `Draggable.PreviewProvider` can set the container for a whole subtree.
   */
  container?: DragPreviewContainer;
}

DragSnappedLocalPointOptionsHide

type DragSnappedLocalPointOptions = {
  /**
   * The point to snap. `'pointer'` uses the pointer position. `'source'` applies
   * the grab offset first, so the result represents the dragged element's leading
   * edges. Use `'source'` when committing the element's position. Falls back to
   * `'pointer'` when no grab offset is available.
   * @default 'pointer'
   */
  anchor?: 'pointer' | 'source';
}

DragSnapStepsHide

type DragSnapSteps = { x?: number; y?: number }

DragSourceHide

type DragSource<TData = unknown> = {
  /** The draggable's own DOM element. */
  element: HTMLElement;
  /**
   * Human-readable name supplied by the draggable's `label`, used by the default
   * screen-reader announcements. `undefined` when the source was registered without one.
   */
  label: string | undefined;
  /**
   * Identity of the kind supplied by the draggable's `kind`. Test it with the kind's
   * `matches`, which narrows `payload` at the same time.
   */
  kind: symbol;
  /** The element the user pressed. `null` when the whole draggable is its own handle. */
  dragHandle: Element | null;
  /**
   * Data supplied by the draggable's `payload`, evaluated at drag start.
   * `undefined` when the source was registered without one.
   */
  payload: TData;
}

DragStartContextHide

type DragStartContext = {
  /** Pointer state at drag start. */
  input: DragInput;
  /** The draggable's own DOM element. */
  element: HTMLElement;
  /** The element the user pressed. `null` when the whole draggable is its own handle. */
  dragHandle: Element | null;
}

DragStartEventHide

type DragStartEvent<TSourceData = unknown> = {
  location: DragLocationHistory;
  source: DragSource<TSourceData>;
  /**
   * The input method driving the drag.
   * This is the reliable way to detect a keyboard drag, as
   * `location.current.input.pointerType` is `null` for those.
   */
  mode: DragMode;
}

DragStartEventDetailsHide

type DragStartEventDetails =
  { reason: 'pointer'; event: PointerEvent } | { reason: 'keyboard'; event: KeyboardEvent }

DropTargetChangeEventHide

type DropTargetChangeEvent<TSourceData = unknown> = {
  location: DragLocationHistory;
  source: DragSource<TSourceData>;
  /**
   * The input method driving the drag.
   * This is the reliable way to detect a keyboard drag, as
   * `location.current.input.pointerType` is `null` for those.
   */
  mode: DragMode;
}

DropTargetChangeEventDetailsHide

type DropTargetChangeEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'keyboard'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | KeyboardEvent }
  | { reason: 'outside-release'; event: PointerEvent | KeyboardEvent }
  | { reason: 'pointer-down'; event: PointerEvent }
  | { reason: 'focus-out'; event: FocusEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'window-blur'; event: FocusEvent }
  | { reason: 'page-hidden'; event: Event }
  | { reason: 'pointer-canceled'; event: PointerEvent }
  | { reason: 'capture-lost'; event: PointerEvent }
  | { reason: 'missed-release'; event: PointerEvent }
  | { reason: 'document-detached'; event: Event }
  | { reason: 'handler-error'; event: Event }

DropTargetRecordHide

type DropTargetRecord<TLocalData = unknown> = {
  /** The drop target's own DOM element. */
  element: Element;
  /**
   * Human-readable name supplied by the drop target's `label`, used by the default
   * screen-reader announcements. `undefined` when the target was registered without one.
   */
  label: string | undefined;
  /**
   * Identity of the kind supplied by the drop target's `kind`, or `undefined` when the
   * target was registered without one. Test it with the kind's `matches`, which narrows
   * `payload` at the same time.
   */
  kind: symbol | undefined;
  /**
   * Data supplied by the drop target's `payload`.
   * `undefined` when the target was registered without one.
   */
  payload: TLocalData;
  /**
   * Where the pointer sat inside this target when the target was resolved, as a fraction
   * of the target's border box on each axis. Use it when the drop resolves to a value
   * spread across the target rather than to the target itself:
   *
   * ```tsx
   * <DropTarget.Root
   *   accept={eventKind}
   *   onDrop={({ self }) => {
   *     schedule(self.getLocalPoint().y * MINUTES_PER_DAY);
   *   }}
   * />
   * ```
   *
   * The first call measures the target. Later calls on the same record reuse the
   * measurement. Records are rebuilt on every move.
   *
   * Not clamped: an ancestor in the stack can have the pointer outside its own box, so
   * clamp where the domain requires it. Both axes report `0` for a target with no extent,
   * including one detached since the drag began.
   */
  getLocalPoint: () => DragLocalPoint;
  /**
   * Returns `getLocalPoint()` rounded to the target's `snap` steps and clamped
   * between `0` and `1`:
   *
   * ```tsx
   * <DropTarget.Root
   *   accept={eventKind}
   *   snap={{ y: 96 }}
   *   onDrop={({ source, self }) => {
   *     // Already a multiple of 15 minutes.
   *     schedule(source.payload.id, self.getSnappedLocalPoint().y * MINUTES_PER_DAY);
   *   }}
   * />
   * ```
   *
   * Pass `{ anchor: 'source' }` to snap the dragged element's leading edges instead
   * of the pointer. An axis without declared steps returns its clamped raw fraction.
   * This method shares the measurement from `getLocalPoint()`.
   */
  getSnappedLocalPoint: (options?: DragSnappedLocalPointOptions) => DragLocalPoint;
}

UseDraggableActiveDragReturnValueHide

type UseDraggableActiveDragReturnValue<TData = unknown> = DragSource<TData> | null