Draggable

Drag and drop for pointer input, with drop targets, previews, sorting, and auto-scrolling.

Drag me

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

import * as React from 'react';

import styles from './hero.module.css';

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

  return (
    <Draggable.Provider>
      <Draggable.Target
        ref={surfaceRef}
        className={styles.Surface}
        onDraggableDrop={({ target }) => {
          const point = target.getSnappedLocalPoint({ anchor: 'source' });
          const rect = target.element.getBoundingClientRect();
          setPosition({
            x: point.x * rect.width - target.element.clientLeft,
            y: point.y * rect.height - target.element.clientTop,
          });
        }}
      >
        <Draggable.Root
          modifiers={Draggable.restrictToElement(surfaceRef)}
          className={styles.Card}
          style={{ left: position.x, top: position.y }}
        >
          Drag me
          <Draggable.Preview />
        </Draggable.Root>
      </Draggable.Target>
    </Draggable.Provider>
  );
}

Usage guidelines

Dragging is a pointer enhancement: Draggable responds to mouse, touch, and pen input only. Every action that can be done by dragging must also be possible with a keyboard, a click, or a tap.
Provide the alternative in your application: A “Move to” menu, move buttons, or a shortcut on the focused item such as Alt+← and Alt+→ all work. Have them call the same function as the drop handler so both paths apply the same rules. After a keyboard move, keep focus on the moved item and announce the result in a live region. The sortable list demos show this.
Drag handles are not controls: <Draggable.Handle> isn’t focusable and has no keyboard behavior. Mark it aria-hidden="true" when it only contains a decorative icon, and don’t rely on it as the keyboard entry point.
Drags stay within the page: Draggable tracks pointer events rather than the browser’s native drag and drop. It can’t move data between browser windows or receive files from the operating system. See Native file drops.
Use it for spatial interactions: Reordering lists, moving items between regions, and positioning items on a canvas are good fits. To pick a value from a list, use a component such as Select instead.

Anatomy

Import the component and assemble its parts:

Anatomy

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

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

<Draggable.Provider>
  <Draggable.Viewport>
    <Draggable.CollisionProvider kind={item}>
      <Draggable.Root kind={item}>
        <Draggable.Handle />
        <Draggable.Preview />
      </Draggable.Root>
    </Draggable.CollisionProvider>

    <Draggable.Target accept={item} />
  </Draggable.Viewport>
</Draggable.Provider>

<Draggable.Root> is an element that can be picked up, and <Draggable.Target> is a place where it can be dropped. Both need a <Draggable.Provider> above them. The provider renders no element of its own.

The remaining parts are optional:

<Draggable.Handle> restricts where a drag can start. See Drag handle.
<Draggable.Preview> customizes what follows the pointer. See Drag preview.
<Draggable.CollisionProvider> groups items that can be reordered. See Sorting a list.
<Draggable.Viewport> marks a scroll container that should auto-scroll during a drag. See Auto-scrolling.

One shared manager handles every drag on the page, so a <Draggable.Provider> doesn’t isolate its contents from other providers. It does two things. It defines the default kind for the parts inside it, and it gives custom previews access to React context, so place it inside any context providers a custom preview needs to read.

Kinds and payloads

A kind identifies a type of draggable item. Create one with Draggable.createKind, pass it to the kind prop of a <Draggable.Root>, and list it in the accept prop of the targets that take it. A target ignores drags of any other kind.

The type argument of createKind declares the item’s payload. The payload is any value you attach to a draggable, and it’s available as source.payload in every drop target and event handler that accepts the kind.

Declaring a kind with a payload

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

<Draggable.Root kind={card} payload={id} />;
<Draggable.Target accept={card} onDraggableDrop={({ source }) => move(source.payload)} />

A kind declared with a payload type requires the payload prop. Omit the type argument when the kind alone identifies the item:

A kind without a payload

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

<Draggable.Root kind={divider} />

Base UI tracks the payload by identity. Prefer a primitive such as an ID, as above. When the payload has to be an object, memoize it so that unrelated re-renders don’t replace it. A new object during a drag re-notifies useActiveDrag subscribers and discards any updatePayload call:

A memoized object payload

const payload = React.useMemo(() => ({ id, column }), [id, column]);

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

Each createKind call creates a unique identity, so two calls with the same name don’t match. Declare each kind once, usually at module scope, and share the same value between the sources and targets of an interaction. The name is only a debugging aid.

When kind and accept are both omitted, a source and a target match as long as they’re inside the same <Draggable.Provider>. This is enough for a single self-contained interaction, like the demo at the top of this page.

Matching several kinds

A target, viewport, or monitor can accept an array of kinds. source.payload is then a union of their payload types. Use a kind’s matches method to narrow it:

Accepting two kinds

const task = Draggable.createKind<Task>('task');
const file = Draggable.createKind<Attachment>('file');

<Draggable.Target
  accept={[task, file]}
  onDraggableDrop={({ source }) => {
    if (file.matches(source)) {
      upload(source.payload.mime);
    } else if (task.matches(source)) {
      addTask(source.payload.id);
    }
  }}
/>

Use Draggable.anyKind to accept every drag, for example on a trash zone. Its source.payload is unknown until narrowed with matches.

Drag events

Drag sources and drop targets both fire event handlers as a drag progresses. Every handler receives an event object first, and an eventDetails object second with the event reason and the native event.

When extracting a handler, use the types on its component namespace, such as Draggable.Root.MoveStartEvent<Payload>, Draggable.Root.MoveStartEventDetails, and Draggable.Root.MoveStartEventReason. Target handlers expose corresponding types such as Draggable.Target.DropEvent<SourcePayload, TargetPayload> and Draggable.Target.DropEventDetails. Event types also accept drag-data type arguments when needed. The existing standalone event types remain available for shared handlers and imperative registrations.

Drag source events

<Draggable.Root> fires the handlers below, in this order:

Following a drag from start to end

<Draggable.Root
  kind={card}
  payload={id}
  // Fires just before the drag starts. Call `eventDetails.cancel()` to prevent it.
  onBeforeMoveStart={({ input }, eventDetails) => {
    if (input.altKey) {
      eventDetails.cancel();
    }
  }}
  // Fires once when the drag starts. The preview exists by then, so the
  // source can be measured or restyled safely.
  onMoveStart={({ source }) => console.log('lifted', source.payload)}
  // Fires as the pointer moves, at most once per animation frame.
  onMove={({ location }) => {
    const { clientX, clientY } = location.current.input;
    console.log('at', clientX, clientY);
  }}
  // Fires when the drop targets under the pointer change.
  onTargetChange={({ location }) =>
    console.log('over', location.current.dropTargets[0]?.payload ?? 'nothing')
  }
  // Fires once when the drag ends, whether it was dropped, released
  // outside a target, or canceled.
  onMoveEnd={(event, eventDetails) => {
    if (eventDetails.reason === 'drop' && event.dropTarget !== null) {
      console.log('dropped on', event.dropTarget.payload);
    }
  }}
/>

Commit a successful drop in onMoveEnd when eventDetails.reason is 'drop'. A release outside any target also ends with event.canceled set to false, so that flag alone doesn’t identify a drop. When the handler also clears temporary state, use try/finally so the cleanup runs even if committing throws:

Committing a drop

<Draggable.Root
  onMoveEnd={(event, eventDetails) => {
    try {
      if (eventDetails.reason === 'drop' && event.dropTarget !== null) {
        commitMove(event.source.payload, event.dropTarget.payload);
      }
    } finally {
      clearDragState();
    }
  }}
/>

Every event carries the drag source and a location history:

location.current is the pointer position and the drop targets under it, innermost first, for this event.
location.previous is the same information at the previous event. Compare it with location.current to detect what changed.
location.initial is where the drag began.
location.grabOffset is the pointer’s offset from the source’s top-left corner at pickup.

A drag keeps going if the source element leaves the DOM, for example when a virtualized list unmounts the dragged row. Identify the dragged item with source.payload rather than its element. To stop a drag from code, for example when the dragged record is deleted, call cancelDrag.

To observe every drag on the page rather than one source, use useDragMonitor.

Drop target events

<Draggable.Target> fires the handlers below. They receive the drag source, the target’s own record as target, and the same location history:

Reacting to a drag over a target

<Draggable.Target
  accept={card}
  payload={zone}
  // Fires when the drag moves over this target.
  onDraggableEnter={({ source }) => console.log(source.payload, 'entered')}
  // Fires on every animation frame the pointer moves while over this target.
  // Hover feedback such as drop indicators belongs here.
  onDraggableMove={({ location }) => {
    const { clientX, clientY } = location.current.input;
    highlightSlotAt(clientX, clientY);
  }}
  // Fires when the drag moves off this target, or ends.
  onDraggableLeave={() => clearHighlight()}
  // Fires when the drag is released over this target. Only the innermost
  // target under the pointer receives it, and it never fires on a cancel.
  onDraggableDrop={({ source, target }) => move(source.payload, target.payload)}
/>

onDraggableStart fires only when this target is already under the pointer when the drag starts. To observe every drop regardless of which target received it, use the source’s or a monitor’s onMoveEnd and check for the 'drop' reason. When a drag ends on a target, the source’s onMoveEnd runs first, then the target’s onDraggableDrop, then the monitors’ onMoveEnd.

Use onDraggableEnter and onDraggableLeave together to react to a pause over a target. For example, expand a collapsed group after the drag hovers it for a moment:

Expanding a group on hover

<Draggable.Target
  accept={card}
  onDraggableEnter={() => dwellTimer.start(500, () => setExpanded(true))}
  onDraggableLeave={() => dwellTimer.clear()}
/>

Drop targets

<Draggable.Target> marks where a drag can be released. Pass the kinds it takes to accept, and handle the drop in onDraggableDrop:

A basic drop target

<Draggable.Target accept={card} onDraggableDrop={({ source }) => archive(source.payload)} />

Targets can be nested. The innermost target under the pointer that accepts the drag receives the drop. See Drop target events for the full set of handlers.

Accepting drops

accept decides by kind. For rules that depend on the item being dragged or on the target’s current state, add canDrop. Base UI calls it every time it looks for a target under the pointer. Return false to skip this target and let an ancestor receive the drop, or 'reject' to block the drop on this target and everything inside it:

A column with a capacity

<Draggable.Target
  accept={card}
  canDrop={({ source }) => !column.cards.includes(source.payload) && column.cards.length < limit}
/>

Use disabled to turn a target off entirely. See Nested drop targets for how these options interact.

Identifying a target

Most targets don’t need extra data. A target rendered for each row or column can use that value directly in its handlers:

A target that knows where it is

<Draggable.Target accept={card} onDraggableDrop={({ source }) => move(source.payload, zone)} />

Pass payload when other code must identify the target, for instance a monitor reading location.current.dropTargets. The value is available as target.payload in the target’s own handlers:

Identifying the target from its payload

<Draggable.Target
  accept={card}
  payload={zone}
  onDraggableDrop={({ source, target }) => move(source.payload, target.payload)}
/>

A target can also declare its own kind. This lets a shared handler tell several types of target apart with matches, and types target.payload at the same time:

Telling target types apart

const dayCell = Draggable.createKind<number>('day-cell');

<Draggable.Target kind={dayCell} accept={card} payload={dayMs} />

Auto-scrolling

Scroll containers don’t scroll during a drag unless you opt them in. Render <Draggable.Viewport> on each container that should scroll, including nested ones. The board below registers both lists, and slows down the second one.

Drag the card into either list, at the slot you want. Both lists scroll near their edges; the second list scrolls more slowly.

Renew passport

Default

Water the plants

Reply to Alex

Book a dentist

Send the invoice

Plan the sprint

Call the bank

Buy groceries

Clean the desk

Book the flights

Review the draft

Update the budget

Move the standup

Copy the keys

Sort the photos

Reboot the router

Wrap the gift

maxSpeed={150}

Pay the rent

Update resume

Back up the laptop

Read the docs

Fix the bug

Write the tests

Email the team

Order supplies

Write the changelog

Bump the deps

Fix the flaky test

Tag the release

Check the metrics

Onboard the intern

Book the retro

Archive the branch

index.tsx GripIcon.tsx DragPageAutoScroll.tsx hero.module.css

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

import * as React from 'react';
import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
import { GripIcon } from './GripIcon';
import { DragPageAutoScroll } from './DragPageAutoScroll';

import styles from './hero.module.css';

type Zone = 'plain' | 'slow';

interface Task {
  id: string;
  label: string;
}

const taskKind = Draggable.createKind<Task>('task');

const INITIAL_TASKS: Record<Zone, Task[]> = {
  plain: [
    { id: 'plants', label: 'Water the plants' },
    { id: 'reply', label: 'Reply to Alex' },
    { id: 'dentist', label: 'Book a dentist' },
    { id: 'invoice', label: 'Send the invoice' },
    { id: 'sprint', label: 'Plan the sprint' },
    { id: 'bank', label: 'Call the bank' },
    { id: 'groceries', label: 'Buy groceries' },
    { id: 'desk', label: 'Clean the desk' },
    { id: 'flights', label: 'Book the flights' },
    { id: 'draft', label: 'Review the draft' },
    { id: 'budget', label: 'Update the budget' },
    { id: 'standup', label: 'Move the standup' },
    { id: 'keys', label: 'Copy the keys' },
    { id: 'photos', label: 'Sort the photos' },
    { id: 'router', label: 'Reboot the router' },
    { id: 'gift', label: 'Wrap the gift' },
  ],
  slow: [
    { id: 'rent', label: 'Pay the rent' },
    { id: 'resume', label: 'Update resume' },
    { id: 'backup', label: 'Back up the laptop' },
    { id: 'docs', label: 'Read the docs' },
    { id: 'bug', label: 'Fix the bug' },
    { id: 'tests', label: 'Write the tests' },
    { id: 'team', label: 'Email the team' },
    { id: 'supplies', label: 'Order supplies' },
    { id: 'changelog', label: 'Write the changelog' },
    { id: 'deps', label: 'Bump the deps' },
    { id: 'flaky', label: 'Fix the flaky test' },
    { id: 'release', label: 'Tag the release' },
    { id: 'metrics', label: 'Check the metrics' },
    { id: 'onboard', label: 'Onboard the intern' },
    { id: 'retro', label: 'Book the retro' },
    { id: 'archive', label: 'Archive the branch' },
  ],
};

const UPCOMING = ['Renew passport', 'Cancel the trial', 'Refill the coffee', 'Label the boxes'];

// Resolve the insertion slot closest to the pointer, including positions outside
// the currently visible portion of the list.
function resolveDrop(container: HTMLElement, clientY: number): { index: number; slotY: number } {
  // The dragged card's preview is a clone and carries the same `data-card`.
  // Skip it: it follows the pointer and is not a real slot.
  const cards = Array.from(
    container.querySelectorAll<HTMLElement>('[data-card]:not([data-drag-preview])'),
  );
  if (cards.length === 0) {
    return { index: 0, slotY: container.getBoundingClientRect().top };
  }

  const slotYs = [cards[0].getBoundingClientRect().top];
  for (let i = 1; i < cards.length; i += 1) {
    const prev = cards[i - 1].getBoundingClientRect();
    const curr = cards[i].getBoundingClientRect();
    slotYs.push((prev.bottom + curr.top) / 2);
  }
  slotYs.push(cards[cards.length - 1].getBoundingClientRect().bottom);

  let index = 0;
  let bestDy = Infinity;
  for (let i = 0; i < slotYs.length; i += 1) {
    const dy = Math.abs(clientY - slotYs[i]);
    if (dy < bestDy) {
      bestDy = dy;
      index = i;
    }
  }
  return { index, slotY: slotYs[index] };
}

function Card({ task, draggable }: { task: Task; draggable?: boolean }) {
  return (
    <Draggable.Root
      kind={taskKind}
      payload={task}
      previewKey={task.id}
      disabled={!draggable}
      data-card
      data-id={task.id}
      className={styles.Card}
    >
      <GripIcon className={styles.Grip} />
      {task.label}
    </Draggable.Root>
  );
}

function DropZone({
  label,
  tasks,
  maxSpeed,
  onInsert,
}: {
  label: string;
  tasks: Task[];
  // Left out on the plain list, so it keeps the engine's default speed.
  maxSpeed?: number;
  onInsert: (task: Task, index: number) => void;
}) {
  const listRef = React.useRef<HTMLDivElement | null>(null);
  // Y offset (in the list's scrolled content) of the line previewing the drop.
  const [dropLineTop, setDropLineTop] = React.useState<number | null>(null);

  return (
    <Draggable.Target
      className={styles.Zone}
      accept={taskKind}
      onDraggableMove={({ location }) => {
        const container = listRef.current;
        if (!container) {
          return;
        }
        const { slotY } = resolveDrop(container, location.current.input.clientY);
        setDropLineTop(slotY - container.getBoundingClientRect().top + container.scrollTop);
      }}
      onDraggableLeave={() => setDropLineTop(null)}
      onDraggableDrop={({ source, location }) => {
        const container = listRef.current;
        if (container) {
          const { index } = resolveDrop(container, location.current.input.clientY);
          onInsert(source.payload, index);
        }
        setDropLineTop(null);
      }}
    >
      <span className={styles.Label}>{label}</span>
      <Draggable.Viewport ref={listRef} className={styles.Cards} maxSpeed={maxSpeed}>
        {tasks.map((task) => (
          <Card key={task.id} task={task} />
        ))}
        {dropLineTop != null && (
          <div className={styles.DropLine} style={{ top: dropLineTop }} aria-hidden="true" />
        )}
      </Draggable.Viewport>
    </Draggable.Target>
  );
}

export default function AutoScrollBoard() {
  const [tasks, setTasks] = React.useState<Record<Zone, Task[]>>(INITIAL_TASKS);
  // Index into `UPCOMING`, so the tray always holds another card to drag.
  const [handedOut, setHandedOut] = React.useState(0);
  const rootRef = React.useRef<HTMLDivElement | null>(null);
  // Id of the card just dropped; scrolled back into view after the commit.
  const droppedIdRef = React.useRef<string | null>(null);

  const pending: Task = {
    id: `new-${handedOut}`,
    label: UPCOMING[handedOut % UPCOMING.length],
  };

  function insert(zone: Zone, task: Task, index: number) {
    droppedIdRef.current = task.id;
    setTasks((prev) => ({
      ...prev,
      [zone]: [...prev[zone].slice(0, index), task, ...prev[zone].slice(index)],
    }));
    setHandedOut((count) => count + 1);
  }

  // The drop can land the card outside the visible window, since the list
  // reflows around it. Reveal it so the insertion is never invisible.
  useIsoLayoutEffect(() => {
    const id = droppedIdRef.current;
    if (id == null) {
      return;
    }
    droppedIdRef.current = null;
    rootRef.current
      ?.querySelector(`[data-id="${id}"]:not([data-drag-preview])`)
      ?.scrollIntoView({ block: 'nearest' });
  }, [tasks]);

  return (
    <Draggable.Provider>
      <DragPageAutoScroll accept={taskKind} />
      <div ref={rootRef} className={styles.Root}>
        <p className={styles.Hint}>
          Drag the card into either list, at the slot you want. Both lists scroll near their edges;
          the second list scrolls more slowly.
        </p>
        <div className={styles.Tray}>
          <Card key={pending.id} task={pending} draggable />
        </div>
        <div className={styles.Columns}>
          <DropZone
            label="Default"
            tasks={tasks.plain}
            onInsert={(task, index) => insert('plain', task, index)}
          />
          <DropZone
            label="maxSpeed={150}"
            tasks={tasks.slow}
            maxSpeed={150}
            onInsert={(task, index) => insert('slow', task, index)}
          />
        </div>
      </div>
    </Draggable.Provider>
  );
}

A viewport scrolls while the pointer is near one of its edges and more content remains in that direction. It scrolls on the axes whose overflow is auto or scroll. Base UI looks for drop targets again as the content scrolls, so a target that slides under a stationary pointer can receive the drop.

Nesting follows the DOM tree. The innermost viewport scrolls first, and an ancestor viewport scrolls on the axes the inner one doesn’t use or has exhausted. A vertical column inside a horizontal board scrolls each on its own axis.

Pass disabled to pause a viewport, for example while a list is filtered. Pass accept to scroll only for some kinds. To change the speed, restrict the direction, or scroll something that isn’t a scroll container, see the examples.

Auto-scrolling only for cards

<Draggable.Viewport accept={card} disabled={isFiltered} />

Scrolling the page

The page doesn’t scroll during a drag by default. Since <Draggable.Viewport> renders an element, register the document with useDragDropManager instead. It accepts the same options as the viewport part:

Letting the page scroll vertically

const manager = Draggable.useDragDropManager();

React.useEffect(
  () =>
    manager.registerAutoScroller(document.documentElement, () => ({
      onDragScroll({ direction }, eventDetails) {
        if (direction === 'horizontal') {
          eventDetails.cancel();
        }
      },
    })),
  [manager],
);

Inner viewports take precedence on the axes they use. overflow: hidden on <html> or <body> prevents page scrolling on that axis, which includes the scroll lock of a modal Dialog.

Testing

A drag is a sequence of pointer events, so it can be driven from a test. Most of what’s worth testing isn’t the gesture, though. The drop handler and the keyboard alternative call the same application function, so test that function, or the keyboard path with ordinary Testing Library interactions, and keep a few gesture tests for the wiring between the parts.

Choosing an environment

jsdom has no layout and no document.elementFromPoint, so Base UI can’t find a drop target there. A drag in jsdom starts, moves, and ends normally, but always with the 'outside-release' reason. Use jsdom to test activation, disabled and onBeforeMoveStart, the lifecycle handlers, data-dragging, and the preview. Use a real browser, through Vitest browser mode or an end-to-end tool, to test drops, drag-over styling, sorting, and auto-scrolling.

Simulating a drag

Use the pointer API of @testing-library/user-event. Press on the source, move past the activation threshold, then release. Native HTML5 drag events such as dragstart don’t start a Base UI drag.

A mouse drag

const user = userEvent.setup();
const card = screen.getByRole('button', { name: 'Write the spec' });

await user.pointer([
  { keys: '[MouseLeft>]', target: card, coords: { x: 0, y: 0 } },
  // Past the 5px threshold: this is what starts the drag.
  { coords: { x: 0, y: 40 } },
  { coords: { x: 0, y: 120 } },
  { keys: '[/MouseLeft]' },
]);

Touch starts a drag after a 250ms hold, so advance fake timers between the press and the move. Dispatch the events directly in that case, with the same pointerId throughout and the moves on document:

A touch drag

vi.useFakeTimers();
fireEvent.pointerDown(card, { pointerId: 1, pointerType: 'touch', clientX: 0, clientY: 0 });
await act(async () => {
  vi.advanceTimersByTime(300);
});
fireEvent.pointerMove(document, { pointerId: 1, pointerType: 'touch', clientX: 0, clientY: 120 });
fireEvent.pointerUp(document, { pointerId: 1, pointerType: 'touch', clientX: 0, clientY: 120 });

Waiting and asserting

onMoveStart and onMoveEnd fire synchronously with the event that causes them. Movement and drag-over updates run once per animation frame, so wait for them:

Waiting for drag-over feedback

await waitFor(() => {
  expect(screen.getByRole('group', { name: 'Done' })).toHaveAttribute('data-drag-over');
});

Assert on what a user could observe: the data attributes on the source and targets, and the arguments your handlers received. Handlers take two arguments, so check mock.calls[0][0] for the event and mock.calls[0][1] for the details rather than toHaveBeenCalledWith with a single argument. A successful drop has the 'drop' reason:

Asserting on a drop

expect(onMoveEnd).toHaveBeenCalledTimes(1);
expect(onMoveEnd.mock.calls[0][0].dropTarget?.payload).toBe('done');
expect(onMoveEnd.mock.calls[0][1].reason).toBe('drop');

Cleaning up

Every drag on the page goes through one manager, so a drag left running leaks into the next test. End every drag you start, with a release or Esc, and do it in afterEach when a test asserts mid-drag. Restore real timers after using fake ones.

Examples

Drag handle

By default, the whole element starts a drag. Render <Draggable.Handle> inside the root to start drags from that element only, so the rest of the item stays interactive. A draggable uses its first handle and ignores any other.

Dragging by a handle

<Draggable.Root kind={card} payload={id}>
  <Draggable.Handle aria-hidden="true">
    <Grip />
  </Draggable.Handle>
  {label}
</Draggable.Root>

Visitors

2,420Last 7 days

Conversion

3.8%Up 0.4%

Drop widget

index.tsx GripIcon.tsx dashboardWidgets.ts handle.module.css dashboardStatus.module.css

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

import * as React from 'react';
import { GripIcon } from './GripIcon';
import { SLOTS, useDashboardWidgets, type SlotId, type WidgetData } from './dashboardWidgets';

import styles from './handle.module.css';
import statusStyles from './dashboardStatus.module.css';

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

function Widget({
  widget,
  onKeyDown,
}: {
  widget: WidgetData;
  onKeyDown: (event: React.KeyboardEvent<HTMLElement>, widgetId: string) => void;
}) {
  return (
    <Draggable.Root
      kind={widgetKind}
      payload={widget.id}
      className={styles.Widget}
      data-widget-id={widget.id}
      tabIndex={0}
      aria-keyshortcuts="Alt+ArrowLeft Alt+ArrowRight"
      onKeyDown={(event) => onKeyDown(event, widget.id)}
    >
      <div className={styles.WidgetHeader}>
        <Draggable.Handle className={styles.Handle}>
          <GripIcon className={styles.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,
  onWidgetKeyDown,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
  onWidgetKeyDown: (event: React.KeyboardEvent<HTMLElement>, widgetId: string) => void;
}) {
  return (
    <Draggable.Target
      role="group"
      aria-label={label}
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDraggableDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? (
        <Widget widget={widget} onKeyDown={onWidgetKeyDown} />
      ) : (
        <span className={styles.Empty}>Drop widget</span>
      )}
    </Draggable.Target>
  );
}

export default function HandleDashboard() {
  const { dashboardRef, widgets, moveWidget, onWidgetKeyDown, announcement } =
    useDashboardWidgets();

  return (
    <Draggable.Provider>
      <div ref={dashboardRef} className={styles.Root}>
        <div role="status" className={statusStyles.Status}>
          {announcement}
        </div>
        <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}
              onWidgetKeyDown={onWidgetKeyDown}
            />
          ))}
        </div>
      </div>
    </Draggable.Provider>
  );
}

The handle renders a <span> and isn’t focusable. Keep the item operable through its own controls or shortcuts, as described in the usage guidelines. The dashboard demos on this page move the focused widget with Alt+← and Alt+→.

Disabling a drag

Pass disabled to <Draggable.Root> to prevent an item from being picked up. Clicks and context menus on the element keep working.

A pinned item

<Draggable.Root kind={card} payload={id} disabled={card.pinned} />

When the decision depends on the gesture itself, for example on which handle was pressed or on a modifier key, use onBeforeMoveStart instead. It fires just before a drag starts. Call eventDetails.cancel() to prevent it:

Canceling a drag as it starts

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

Storing data during a drag

Both source and target records let handlers store data for later handlers to read. Declare its type as the second type argument of createKind, and set it with updateDragData. It starts as undefined on each pickup. Initialize source data in onBeforeMoveStart to make it available to target resolution and custom previews. The same source continues into the accepted drag; canceled pickups do not carry their gesture data into the next attempt. For example:

Recording the grab position

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

<Draggable.Root
  kind={card}
  payload={id}
  onBeforeMoveStart={({ source, input }) => {
    const rect = source.element.getBoundingClientRect();
    source.updateDragData({ grabOffsetX: input.clientX - rect.left });
  }}
  onMove={({ source }) => {
    console.log(source.payload, source.dragData?.grabOffsetX);
  }}
/>

To replace the payload itself, call updatePayload. Unlike drag data, the new payload persists after the drag ends, until the payload prop changes.

Activation

A pointer press doesn’t start a drag right away. By default:

Mouse and pen start a drag after 5px of movement.
Touch starts a drag after a 250ms hold with less than 5px of movement. Moving further before that lets the page scroll instead.

Releasing before the threshold keeps the normal click or tap.

Single criterion

One activation object.

Multiple criteria

An array of alternatives. The first match starts the drag.

Start

Target

StatusMove 5px while pressed to activate.

index.tsx activation.module.css

'use client';
import { Draggable, type DragActivationConfig } from '@base-ui/react/draggable';

import * as React from 'react';

import styles from './activation.module.css';

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

interface ActivationMode {
  id: string;
  label: string;
  activation: DragActivationConfig | readonly DragActivationConfig[];
  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: 'double-click',
    label: 'Double-click',
    activation: { type: 'double-click' },
    readyMessage:
      'Double-click to pick up, then click the target to drop. On touch, double-tap and hold, then release on the target. Escape cancels.',
    waitingMessage: 'Double-click or double-tap to pick up…',
  },
  {
    id: 'distance-or-hold',
    label: 'Move 5px or hold 250ms',
    activation: [
      { type: 'distance', distance: 5 },
      { type: 'press-hold', delay: 250 },
    ],
    readyMessage: 'Move 5px or hold for 250ms to activate.',
    waitingMessage: 'Waiting for movement or a hold…',
  },
  {
    id: 'distance-or-double-click',
    label: 'Move 5px or double-click',
    activation: [{ type: 'distance', distance: 5 }, { type: 'double-click' }],
    readyMessage:
      'Move 5px while pressed, or double-click to pick up. On touch, move or double-tap and hold.',
    waitingMessage: 'Waiting for movement or a double-click…',
  },
  {
    id: 'distance-5',
    label: 'Move 5px',
    activation: { type: 'distance', distance: 5 },
    readyMessage: 'Move 5px while pressed to activate.',
    waitingMessage: 'Waiting for 5px of movement…',
  },
  {
    id: 'press-hold',
    label: 'Hold 250ms',
    activation: { type: 'press-hold', delay: 250 },
    readyMessage: 'Press and hold for 250ms to activate.',
    waitingMessage: 'Waiting for the 250ms hold…',
  },
];

const ACTIVATION_GROUPS = [
  {
    label: 'Single criterion',
    description: 'One activation object.',
    modes: ACTIVATION_MODES.filter((mode) => !Array.isArray(mode.activation)),
  },
  {
    label: 'Multiple criteria',
    description: 'An array of alternatives. The first match starts the drag.',
    modes: ACTIVATION_MODES.filter((mode) => Array.isArray(mode.activation)),
  },
];

function hasDoubleClickActivation(activation: ActivationMode['activation']) {
  const criteria = Array.isArray(activation) ? activation : [activation];
  return criteria.some((criterion) => criterion.type === 'double-click');
}

function Puck({
  mode,
  onPhaseChange,
}: {
  mode: ActivationMode;
  onPhaseChange: (phase: Phase) => void;
}) {
  return (
    <Draggable.Root
      className={styles.Puck}
      kind={puckKind}
      activation={mode.activation}
      role="img"
      aria-label="Puck"
      onPointerDown={(event) => {
        if (
          mode.id !== 'immediate' &&
          (!hasDoubleClickActivation(mode.activation) || event.pointerType === 'mouse')
        ) {
          onPhaseChange('waiting');
        }
      }}
      onPointerUp={() => onPhaseChange('ready')}
      onPointerCancel={() => onPhaseChange('ready')}
      onMoveStart={() => onPhaseChange('dragging')}
      onMoveEnd={(_, 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: hasDoubleClickActivation(mode.activation)
      ? 'Move to the target and click or release to drop. Escape cancels.'
      : 'Activated — drag the puck to the target.',
    dropped: 'Dropped. Reset to try again.',
  }[phase];

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

        <div className={styles.ActivationGroups}>
          {ACTIVATION_GROUPS.map((group) => (
            <fieldset key={group.label} className={styles.ActivationGroup}>
              <legend className={styles.GroupLabel}>{group.label}</legend>
              <p className={styles.GroupDescription}>{group.description}</p>
              <div className={styles.Modes}>
                {group.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>
            </fieldset>
          ))}
        </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}>
            <Draggable.Target
              className={styles.Target}
              accept={puckKind}
              onDraggableDrop={() => {
                setDropped(true);
                setPhase('dropped');
              }}
            >
              {dropped && <span className={styles.Puck} data-static="" aria-hidden="true" />}
            </Draggable.Target>
            <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>
    </Draggable.Provider>
  );
}

Pass activation to change the thresholds. It takes one activation method for every pointer type, or a map keyed by mouse, touch, and pen. Unlisted pointer types keep their defaults.

Custom thresholds

<Draggable.Root
  kind={card}
  payload={id}
  activation={{
    mouse: { type: 'distance', distance: 10 },
    touch: { type: 'press-hold', delay: 150 },
  }}
/>

The available methods are:

{ type: 'distance', distance } starts the drag after the pointer moves by that many pixels.
{ type: 'press-hold', delay, tolerance? } starts the drag after holding still for delay milliseconds. Moving more than tolerance pixels (5 by default) cancels the gesture.
{ type: 'immediate' } starts the drag on pointerdown. Use it for a canvas tile whose whole area is meant to be dragged. Pressing a nested button, link, or input still doesn’t start a drag.
{ type: 'double-click' } starts the drag on a double-click or double-tap. See Double-click pickup.

Pass an array to allow several methods at once. The first one to complete starts the drag. An empty array disables pickup.

Drag or hold

<Draggable.Root
  kind={card}
  payload={id}
  activation={[
    { type: 'distance', distance: 12 },
    { type: 'press-hold', delay: 250 },
  ]}
/>

Double-click pickup

With { type: 'double-click' }, a mouse double-click picks the item up. It then follows the pointer without a held button and drops on the next click. With touch or pen, the second tap of a double-tap picks the item up while the pointer is still down, and releasing drops it. Esc or Tab cancels either gesture.

Combine it with another method to keep drag-to-pick-up as well, or use a per-pointer map to enable it for some pointer types only:

Double-click or drag

<Draggable.Root
  kind={card}
  payload={id}
  activation={[{ mouse: { type: 'distance', distance: 5 } }, { mouse: { type: 'double-click' } }]}
/>

Avoid this method on items whose double-click already opens or edits content. The click that drops the item is consumed, so it doesn’t also activate what’s underneath.

For these pickups, eventDetails.reason in onBeforeMoveStart and onMoveStart is 'double-click' instead of 'pointer'.

Constraining movement

A drag follows the pointer freely by default. Pass modifiers to <Draggable.Root> to keep it on one axis, snap it to a grid, or contain it within an element. Modifiers affect both the preview and the point used to find drop targets.

Locking a list to one axis

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

The built-in modifiers are:

restrictToVerticalAxis and restrictToHorizontalAxis lock the drag to one axis.
restrictToParentElement keeps the drag inside the source’s parent element.
restrictToElement(element) keeps the drag inside any element. It accepts an element, a ref, or a function returning one.
restrictToWindowEdges keeps the drag inside the browser viewport.
snapToGrid(size) snaps the drag to a grid anchored at the pickup point. Pass a number, or { x, y } for a rectangular grid.

Pass an array to apply several modifiers in order. Each one receives the previous one’s result:

Combining modifiers

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

In the demo below, restrictToElement keeps each widget inside the dashed frame. The drop position is constrained too, so the slot outside the frame never activates.

Visitors

2,420Last 7 days

Conversion

3.8%Up 0.4%

Drop widget

Outside slotThe drag cannot reach this target.

index.tsx GripIcon.tsx dashboardWidgets.ts containment.module.css dashboardStatus.module.css

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

import * as React from 'react';
import { GripIcon } from './GripIcon';
import { SLOTS, useDashboardWidgets, type SlotId, type WidgetData } from './dashboardWidgets';

import styles from './containment.module.css';
import statusStyles from './dashboardStatus.module.css';

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

function Widget({
  widget,
  frameRef,
  onKeyDown,
}: {
  widget: WidgetData;
  frameRef: React.RefObject<HTMLDivElement | null>;
  onKeyDown: (event: React.KeyboardEvent<HTMLElement>, widgetId: string) => void;
}) {
  return (
    <Draggable.Root
      kind={widgetKind}
      payload={widget.id}
      data-widget-id={widget.id}
      tabIndex={0}
      aria-keyshortcuts="Alt+ArrowLeft Alt+ArrowRight"
      onKeyDown={(event) => onKeyDown(event, widget.id)}
      className={styles.Widget}
      modifiers={Draggable.restrictToElement(frameRef)}
    >
      <div className={styles.WidgetHeader}>
        <GripIcon className={styles.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,
  onWidgetKeyDown,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  frameRef: React.RefObject<HTMLDivElement | null>;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
  onWidgetKeyDown: (event: React.KeyboardEvent<HTMLElement>, widgetId: string) => void;
}) {
  return (
    <Draggable.Target
      role="group"
      aria-label={label}
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDraggableDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? (
        <Widget widget={widget} frameRef={frameRef} onKeyDown={onWidgetKeyDown} />
      ) : (
        <span className={styles.Empty}>Drop widget</span>
      )}
    </Draggable.Target>
  );
}

export default function ContainedDashboard() {
  const { dashboardRef, widgets, moveWidget, onWidgetKeyDown, announcement } =
    useDashboardWidgets();
  const frameRef = React.useRef<HTMLDivElement | null>(null);

  return (
    <Draggable.Provider>
      <div ref={dashboardRef} className={styles.Root}>
        <div role="status" className={statusStyles.Status}>
          {announcement}
        </div>
        <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}
                onWidgetKeyDown={onWidgetKeyDown}
              />
            ))}
          </div>
        </div>
        <Draggable.Target className={styles.OutsideSlot} accept={widgetKind}>
          <strong>Outside slot</strong>
          <span>The drag cannot reach this target.</span>
        </Draggable.Target>
      </div>
    </Draggable.Provider>
  );
}

<Draggable.Preview> also accepts modifiers. Those only constrain the preview, while the drop position still follows the pointer. Use them when leaving an area should cancel the drag rather than drop on the nearest target. For instance, a data grid can keep the preview inside the grid while a release outside it cancels.

Custom modifiers

A modifier is a function that receives the proposed point and returns the point to use. It also receives the initialPoint where the drag started, the raw pointer input, the source and preview rectangles, the element’s scale, and the modifier keys held during the current event. It runs on every frame, 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 are in client pixels, matching getBoundingClientRect(). On a zoomed or scaled canvas, multiply a canvas distance by scale to convert it to client pixels. scale is 1 when nothing is scaled.

Moving by 20 canvas units

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

The ctrlKey, shiftKey, altKey, and metaKey flags let a modifier react to keys held during the drag. Pressing or releasing a key reapplies the modifiers on the next frame.

Snapping to 45° while Shift is held

const snapToAngle: DragModifier = ({ point, shiftKey, initialPoint }) => {
  if (!shiftKey) {
    return point;
  }
  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,
  };
};

Drag preview

While dragging, a copy of the source element follows the pointer. This clone keeps the element’s classes, form values, canvas drawings, and scroll positions. Base UI renders it in the browser’s top layer, so no scroll container clips it and nothing on the page paints over it.

Base UI rewrites the clone’s IDs to keep the document valid, so style it with classes or [data-drag-preview] rather than ID selectors. Styles that depend on :hover or :focus don’t apply to it. The clone also leaves out content that lives outside the DOM, such as a WebGL canvas, a playing video, or a shadow DOM. Render a custom preview in those cases, or when the source is heavy enough that cloning it takes a visible moment.

Render <Draggable.Preview> without children to configure how the clone is placed. It renders no element of its own in that case:

Placing the clone under the pointer

<Draggable.Root kind={card} payload={id}>
  {label}
  <Draggable.Preview offset="pointer" />
</Draggable.Root>

Pass disabled to drag without any preview. The drag still runs and targets still respond, which suits a canvas that draws its own feedback:

Dragging without a preview

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

Custom preview

Pass children to <Draggable.Preview> to show something other than a clone. Keep pointer-events: none on the preview so it doesn’t block the drop targets under it. The dashboard below drags each widget as a compact badge:

A badge instead of a clone

<Draggable.Root kind={widget} payload={id}>
  {title}
  <Draggable.Preview className="Badge" offset="pointer">
    <span>{value}</span>
    {title}
  </Draggable.Preview>
</Draggable.Root>

Visitors

2,420Last 7 days

Conversion

3.8%Up 0.4%

Drop widget

index.tsx GripIcon.tsx dashboardWidgets.ts badge.module.css dashboardStatus.module.css

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

import * as React from 'react';
import { GripIcon } from './GripIcon';
import { SLOTS, useDashboardWidgets, type SlotId, type WidgetData } from './dashboardWidgets';

import styles from './badge.module.css';
import statusStyles from './dashboardStatus.module.css';

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

function Widget({
  widget,
  onKeyDown,
}: {
  widget: WidgetData;
  onKeyDown: (event: React.KeyboardEvent<HTMLElement>, widgetId: string) => void;
}) {
  return (
    <Draggable.Root
      kind={widgetKind}
      payload={widget.id}
      className={styles.Widget}
      data-widget-id={widget.id}
      tabIndex={0}
      aria-keyshortcuts="Alt+ArrowLeft Alt+ArrowRight"
      onKeyDown={(event) => onKeyDown(event, widget.id)}
    >
      <div className={styles.WidgetHeader}>
        <GripIcon className={styles.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,
  onWidgetKeyDown,
}: {
  id: SlotId;
  label: string;
  widget: WidgetData | undefined;
  onMoveWidget: (widgetId: string, slot: SlotId) => void;
  onWidgetKeyDown: (event: React.KeyboardEvent<HTMLElement>, widgetId: string) => void;
}) {
  return (
    <Draggable.Target
      role="group"
      aria-label={label}
      className={styles.Slot}
      data-empty={widget ? undefined : ''}
      accept={widgetKind}
      canDrop={() => widget === undefined}
      onDraggableDrop={({ source }) => onMoveWidget(source.payload, id)}
    >
      {widget ? (
        <Widget widget={widget} onKeyDown={onWidgetKeyDown} />
      ) : (
        <span className={styles.Empty}>Drop widget</span>
      )}
    </Draggable.Target>
  );
}

export default function CustomPreviewDashboard() {
  const { dashboardRef, widgets, moveWidget, onWidgetKeyDown, announcement } =
    useDashboardWidgets();

  return (
    <Draggable.Provider>
      <div ref={dashboardRef} className={styles.Root}>
        <div role="status" className={statusStyles.Status}>
          {announcement}
        </div>
        <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}
              onWidgetKeyDown={onWidgetKeyDown}
            />
          ))}
        </div>
      </div>
    </Draggable.Provider>
  );
}

Pass a function as children to build the preview from the dragged item. It receives the drag source and runs once when the drag starts. Return null to show no preview for that particular drag.

Building the preview from the payload

<Draggable.Preview kind={card}>
  {({ source }) => <span className="Chip">{source.payload.title}</span>}
</Draggable.Preview>

A custom preview stays mounted even if the source unmounts during the drag. It reads React context from above the nearest <Draggable.Provider>, so place that provider inside any contexts the preview needs.

The preview takes the size of its content. To match the source instead, use the --drag-source-width and --drag-source-height CSS variables:

Matching the source size

.RowPreview {
  width: var(--drag-source-width);
  min-height: var(--drag-source-height);
}

Preview position

Use the offset prop to position the preview relative to the pointer. It works the same for the clone and for custom content.

Positioning the preview

// The default: the preview lifts off the source without shifting.
<Draggable.Preview offset="source" />

// The preview's top-left corner sits under the pointer.
<Draggable.Preview offset="pointer" />

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

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

Preview container

Base UI inserts the preview element next to the source in the DOM, so your CSS reaches it the same way. This extra sibling has two side effects during the drag:

Selectors that count from the end, such as :last-child and :nth-last-child, shift by one.
DOM queries over the siblings include the preview. Exclude it with :not([data-drag-preview]) when measuring.

Pass container to insert the preview somewhere else. It accepts an element, a ref, or a function that receives the source element:

Rendering the preview outside the list

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

Prefer the closest suitable container. The preview loses the source’s ancestors, so descendant selectors such as .Column .Card stop matching. Rules based on the preview’s own classes still apply.

Drag cursor

During a mouse or pen drag, the cursor is grabbing across the whole document, whatever is under the pointer. Pass a different CSS cursor as dragCursor, or false to manage the cursor yourself. Set the resting cursor in your own styles:

Changing the drag cursor

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

The resting cursor

.Card {
  cursor: grab;
}

Base UI injects the cursor rule as a <style> element. See the CSP guide if your content security policy disallows it.

Styling the source and preview

[data-dragging] is present on the source element during the drag. The clone never gets it, so a rule that dims the source leaves the preview intact. [data-drag-preview] is present on the preview only:

Dimming the source

.Card[data-dragging] {
  opacity: 0.4;
}

.Card[data-drag-preview] {
  box-shadow: 0.25rem 0.25rem 0 rgb(0 0 0 / 12%);
}

Base UI prevents text selection on draggables and disables page scrolling during a drag. Avoid setting touch-action on the draggable or its handle, since it interferes with touch dragging. Set it on a wrapper instead.

Animating a drop

After a release, the clone moves to the source’s final position and receives [data-ending-style]. A release outside any target moves it back to the source. Add a translate transition to animate this, and Base UI keeps the clone mounted until the transition ends:

Settling into place

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

The source also receives [data-ending-style] while the clone settles, so it can act as an empty placeholder until the clone arrives:

Hiding the source until the clone arrives

.Card[data-ending-style]:not([data-drag-preview]) {
  color: transparent;
}

Base UI adds no animation of its own. Wrap the transitions you add in a prefers-reduced-motion: no-preference media query to respect the user’s preference.

Drop position within a target

target.getLocalPoint() returns where the pointer is within the target, as a fraction of its size. Each axis is 0 at the left or top edge and 1 at the right or bottom edge. Use it when a drop means a value rather than the target itself, such as a time within a day column:

A drop that means a time

<Draggable.Target
  accept={event}
  payload={day}
  onDraggableDrop={({ source, target }) => {
    schedule(source.payload, day, target.getLocalPoint().y * MINUTES_PER_DAY);
  }}
/>

The value isn’t clamped, because an outer target can have the pointer outside its own box while a nested target is under it. Clamp it where your data requires it.

When the target represents fixed intervals such as 15-minute slots or weekday columns, declare snap and read getSnappedLocalPoint() instead. It rounds the fraction to the nearest step and clamps it between 0 and 1. Step counts divide the target’s box, so you don’t need to know its size in pixels:

A day column with 15-minute slots

<Draggable.Target
  accept={event}
  payload={day}
  snap={{ y: 96 }}
  onDraggableDrop={({ source, target }) => {
    schedule(source.payload, day, target.getSnappedLocalPoint().y * MINUTES_PER_DAY);
  }}
/>

snap also accepts a function that receives the drag source, for a step count that depends on the item.

When moving an element, the value to commit is usually where the element lands rather than where the pointer is. Pass { anchor: 'source' } to snap the dragged element’s top-left corner instead of the pointer:

Snapping the element rather than the pointer

const start = target.getSnappedLocalPoint({ anchor: 'source' }).y * MINUTES_PER_DAY;

snap only changes the value this target reports. To snap the preview itself, use the snapToGrid modifier.

Nested drop targets

When targets are nested, the innermost one that accepts the drag receives the drop. Return false from canDrop to skip a target and let an ancestor receive the drop instead. In the demo, the frame accepts only the chart, so a note released over the frame lands on the canvas behind it.

Chart

Note

Canvas

Frame (charts only)

Drop the chart into the frame

index.tsx nesting.module.css

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

import * as React from 'react';

import styles from './nesting.module.css';

type Location = 'palette' | 'canvas' | 'frame';
type LayerId = 'chart' | 'note';

const layerKind = Draggable.createKind<LayerId>('drop-target/nested-layer');

function ChartIcon() {
  return (
    <svg className={styles.LayerIcon} width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
      <path d="M2.5 13.5h11" fill="none" stroke="currentColor" />
      <rect x="3" y="8" width="2.25" height="4" fill="currentColor" />
      <rect x="6.875" y="5" width="2.25" height="7" fill="currentColor" />
      <rect x="10.75" y="2.5" width="2.25" height="9.5" fill="currentColor" />
    </svg>
  );
}

function NoteIcon() {
  return (
    <svg className={styles.LayerIcon} width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
      <path d="M3 4.5h10M3 8h10M3 11.5h6" fill="none" stroke="currentColor" strokeWidth="1.5" />
    </svg>
  );
}

function Layer({ id }: { id: LayerId }) {
  return (
    <Draggable.Root kind={layerKind} payload={id} className={styles.Layer}>
      {id === 'chart' ? <ChartIcon /> : <NoteIcon />}
      {id === 'chart' ? 'Chart' : 'Note'}
    </Draggable.Root>
  );
}

export default function NestedDropTargets() {
  const [locations, setLocations] = React.useState<Record<LayerId, Location>>({
    chart: 'palette',
    note: 'palette',
  });

  function placeLayer(id: LayerId, location: Location) {
    setLocations((current) => ({ ...current, [id]: location }));
  }

  function renderLayers(location: Location) {
    return (['chart', 'note'] as const)
      .filter((id) => locations[id] === location)
      .map((id) => <Layer key={id} id={id} />);
  }

  return (
    <Draggable.Provider>
      <div className={styles.Root}>
        <div className={styles.Palette}>{renderLayers('palette')}</div>
        <Draggable.Target
          className={styles.Canvas}
          accept={layerKind}
          onDraggableDrop={({ source }) => placeLayer(source.payload, 'canvas')}
        >
          <span className={styles.Label}>Canvas</span>
          <div className={styles.CanvasLayers}>{renderLayers('canvas')}</div>
          <Draggable.Target
            className={styles.Frame}
            accept={layerKind}
            canDrop={({ source }) => source.payload === 'chart'}
            onDraggableDrop={({ source }) => placeLayer(source.payload, 'frame')}
          >
            <span className={styles.Label}>Frame (charts only)</span>
            <div className={styles.FrameLayers}>
              {locations.chart === 'frame' ? (
                <Layer id="chart" />
              ) : (
                <span className={styles.Empty}>Drop the chart into the frame</span>
              )}
            </div>
          </Draggable.Target>
        </Draggable.Target>
      </div>
    </Draggable.Provider>
  );
}

Returning false means “skip this target” rather than “block this area”. A target nested inside it can still receive the drop. Return 'reject' when a rule must block the drop everywhere within the target. For example, a full column should reject cards even over the cards it already contains. A rejecting target receives [data-rejected] while the drag is over it:

Rejecting drops in a full column

<Draggable.Target
  accept={card}
  canDrop={() => (column.cards.length < limit ? true : 'reject')}
  className="Column"
/>

.Column[data-rejected] {
  border-color: red;
}

Styling drop targets

Targets expose their state through data attributes:

[data-accepting] is present on every target that accepts the current drag, from pickup until the drag ends. Use it to reveal every possible destination as soon as a drag starts.
[data-drag-over] is present while the drag is over the target or one of its nested targets.
[data-drag-over-innermost] is present only on the innermost target, which is the one that would receive the drop.
[data-rejected] is present while canDrop returns 'reject' for the current position.

Highlighting targets

.Column[data-accepting] {
  outline: 2px dashed oklch(14.5% 0 0deg / 30%);
}

.Column[data-drag-over] {
  background-color: oklch(97% 0 0deg);
}

.Slot[data-drag-over-innermost] {
  outline: 2px solid oklch(14.5% 0 0deg);
}

[data-accepting] is based on accept alone. A target can carry it and still refuse the drop when canDrop runs.

Tracking these states re-renders the target as the drag moves. Set trackDragOver={false} on targets that don’t use them, for example when every row of a long list is a target. Their handlers still fire and they still receive drops:

A target without drag-over feedback

<Draggable.Target accept={card} trackDragOver={false} onDraggableDrop={handleDrop} />

Native file drops

Base UI drags carry no dataTransfer, so they can’t exchange data with other windows or applications. To accept files from the desktop, add native onDrop and onDragOver handlers next to onDraggableDrop. Both kinds of drop can coexist on the same target:

Accepting files from the desktop

<Draggable.Target
  accept={card}
  onDraggableDrop={handleCardDrop}
  onDrop={handleFileDrop}
  onDragOver={allowFileDrop}
/>

One element with two roles

Use the render prop to give one element two roles. For example, an item that other items can be dropped on:

A source that is also a target

const item = Draggable.createKind<string>('item');

<Draggable.Root
  kind={item}
  payload={id}
  render={<Draggable.Target accept={item} payload={id} />}
/>

Don’t use this pattern to build a sortable list. <Draggable.CollisionProvider> handles that case, including the dragged item’s own position and which side of an item the pointer is on. See Sorting a list.

The same applies to the other parts. A scrollable list that accepts drops can be both a target and a viewport:

A target that is also a viewport

<Draggable.Target accept={card} onDraggableDrop={handleDrop} render={<Draggable.Viewport />} />

Sorting a list

Use <Draggable.CollisionProvider> to reorder a group of draggables. Pass the same kind to the provider and to each <Draggable.Root> inside it. The provider reports which item is under the pointer, and your handlers decide where to insert the dragged item.

Update the order in onMoveEnd. The event’s collision.target.payload identifies the item under the pointer, and collision.target.getLocalPoint() tells which half of it the pointer is in. For a vertical list, a y above 0.5 means the bottom half. collision is null when the drag was canceled, released outside the group, or released over the dragged item itself.

index.tsx sortableTasks.ts sortable.module.css

'use client';
import * as React from 'react';
import { useStableCallback } from '@base-ui/utils/useStableCallback';
import { Draggable } from '@base-ui/react/draggable';
import {
  INITIAL_TASKS,
  moveTask,
  swapTask,
  getTaskRow,
  getTaskDestination,
  sameTaskDestination,
  type TaskDestination,
} from './sortableTasks';
import styles from './sortable.module.css';

const taskKind = Draggable.createKind<string>('sortable-drop-task');

// Memoized with stable handlers, so a reorder only moves DOM nodes instead of
// re-rendering every item on each collision change.
const Task = React.memo(function Task({
  task,
  onSwap,
  placement,
}: {
  task: string;
  placement?: TaskDestination['placement'];
  onSwap: (task: string, direction: 'up' | 'down') => void;
}) {
  const rowRef = React.useRef<HTMLDivElement | null>(null);
  const [selfDrop, setSelfDrop] = React.useState(false);
  const trackSelfDrop = useStableCallback((event: Draggable.MoveStartEvent<string>) => {
    setSelfDrop(event.location.current.dropTargets[0]?.element === rowRef.current);
  });

  return (
    <div data-sortable-row ref={rowRef} className={styles.Row}>
      <Draggable.Root
        kind={taskKind}
        payload={task}
        collisionElement={getTaskRow}
        data-drop-position={placement}
        data-self-drop={selfDrop ? '' : undefined}
        onMoveStart={trackSelfDrop}
        onTargetChange={trackSelfDrop}
        onMoveEnd={() => setSelfDrop(false)}
        render={<button type="button" aria-label={task} />}
        className={styles.Item}
        modifiers={Draggable.restrictToVerticalAxis}
        aria-keyshortcuts="Alt+ArrowUp Alt+ArrowDown"
        onKeyDown={(event) => {
          if (event.altKey && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
            event.preventDefault();
            onSwap(task, event.key === 'ArrowUp' ? 'up' : 'down');
          }
        }}
      >
        {task}
      </Draggable.Root>
    </div>
  );
});

export default function SortableOnDrop() {
  const [tasks, setTasks] = React.useState(INITIAL_TASKS);
  const [destination, setDestination] = React.useState<TaskDestination | null>(null);
  const trackCollision = useStableCallback(
    ({ collision, previousCollision }: Draggable.CollisionProvider.CollisionEvent<string>) => {
      const next = getTaskDestination(collision);
      if (sameTaskDestination(next, getTaskDestination(previousCollision))) {
        return;
      }
      setDestination(next);
    },
  );
  const reorder = useStableCallback((event: Draggable.CollisionProvider.CollisionEvent<string>) => {
    setDestination(null);
    setTasks((current) => moveTask(current, event));
  });
  const swap = useStableCallback((task: string, direction: 'up' | 'down') => {
    setTasks((current) => swapTask(current, task, direction));
  });
  return (
    <Draggable.Provider>
      <Draggable.CollisionProvider
        kind={taskKind}
        onCollisionChange={trackCollision}
        onMoveEnd={reorder}
      >
        <div className={styles.Root} role="group" aria-label="Tasks reordered on drop">
          {tasks.map((task) => (
            <Task
              key={task}
              task={task}
              onSwap={swap}
              placement={destination?.id === task ? destination.placement : undefined}
            />
          ))}
        </div>
      </Draggable.CollisionProvider>
    </Draggable.Provider>
  );
}

To show an insertion indicator, compute the position in onCollisionChange and store it in state. The event includes the previousCollision, so you can skip updates when the position hasn’t changed:

Tracking the insertion position

function getPosition(collision) {
  return (
    collision && {
      id: collision.target.payload,
      placement: collision.target.getLocalPoint().y > 0.5 ? 'after' : 'before',
    }
  );
}

<Draggable.CollisionProvider
  kind={task}
  onCollisionChange={({ collision, previousCollision }) => {
    const next = getPosition(collision);
    const previous = getPosition(previousCollision);
    if (next?.id !== previous?.id || next?.placement !== previous?.placement) {
      setPosition(next);
    }
  }}
  onMoveEnd={({ collision }) => {
    setPosition(null);
    if (collision) {
      moveTask(collision);
    }
  }}
/>

By default, the provider measures each item’s own element. Pass collisionElement to <Draggable.Root> to measure a wrapper instead, for example a padded row so that the gaps between items count too. An empty list has no item to collide with, so render a <Draggable.Target> for it.

Sorting while dragging

To move items as the drag goes, update the order in onCollisionChange instead of onMoveEnd. Compare location.current.input with location.previous.input to place the item according to the pointer’s direction.

index.tsx sortableTasks.ts useSortableAnimation.ts sortable.module.css

'use client';
import * as React from 'react';
import { useStableCallback } from '@base-ui/utils/useStableCallback';
import { Draggable } from '@base-ui/react/draggable';
import {
  INITIAL_TASKS,
  moveTask,
  swapTask,
  getTaskRow,
  getTaskDestination,
  sameTaskDestination,
  type TaskDestination,
} from './sortableTasks';
import { useSortableAnimation } from './useSortableAnimation';
import styles from './sortable.module.css';

const taskKind = Draggable.createKind<string>('sortable-live-task');

// Memoized with stable handlers, so a reorder only moves DOM nodes instead of
// re-rendering every item on each collision change.
const Task = React.memo(function Task({
  task,
  onSwap,
}: {
  task: string;
  onSwap: (task: string, direction: 'up' | 'down') => void;
}) {
  return (
    <div data-sortable-row>
      <Draggable.Root
        kind={taskKind}
        payload={task}
        collisionElement={getTaskRow}
        data-sortable-item
        render={<button type="button" aria-label={task} />}
        className={styles.Item}
        modifiers={Draggable.restrictToVerticalAxis}
        aria-keyshortcuts="Alt+ArrowUp Alt+ArrowDown"
        onKeyDown={(event) => {
          if (event.altKey && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
            event.preventDefault();
            onSwap(task, event.key === 'ArrowUp' ? 'up' : 'down');
          }
        }}
      >
        {task}
      </Draggable.Root>
    </div>
  );
});

export default function SortableLive() {
  const [tasks, setTasks] = React.useState(INITIAL_TASKS);
  const initialOrder = React.useRef(tasks);
  const listRef = useSortableAnimation(tasks);
  const destinationRef = React.useRef<TaskDestination | null>(null);
  const reorder = useStableCallback((event: Draggable.CollisionProvider.CollisionEvent<string>) => {
    const next = getTaskDestination(event.collision);
    const previous = destinationRef.current;
    if (next) {
      const delta = event.location.current.input.clientY - event.location.previous.input.clientY;
      if (delta !== 0) {
        next.placement = delta > 0 ? 'after' : 'before';
      } else if (next.id === previous?.id) {
        next.placement = previous.placement;
      }
    }
    if (sameTaskDestination(next, previous)) {
      return;
    }
    destinationRef.current = next;
    setTasks((current) => moveTask(current, event, next?.placement));
  });
  const swap = useStableCallback((task: string, direction: 'up' | 'down') => {
    setTasks((current) => swapTask(current, task, direction));
  });
  return (
    <Draggable.Provider>
      <Draggable.CollisionProvider
        kind={taskKind}
        onMoveStart={() => {
          initialOrder.current = tasks;
          destinationRef.current = null;
        }}
        onCollisionChange={reorder}
        onMoveEnd={(event) => {
          if (event.canceled || !event.dropTarget) {
            setTasks(initialOrder.current);
          } else {
            reorder(event);
          }
          destinationRef.current = null;
        }}
      >
        <div
          ref={listRef}
          className={styles.Root}
          role="group"
          aria-label="Tasks reordered while dragging"
        >
          {tasks.map((task) => (
            <Task key={task} task={task} onSwap={swap} />
          ))}
        </div>
      </Draggable.CollisionProvider>
    </Draggable.Provider>
  );
}

Save the original order in onMoveStart, and restore it in onMoveEnd when event.canceled is true or event.dropTarget is null. A release over the dragged item itself has a dropTarget but a null collision. Keep the current order in that case.

When items animate into their new positions, pass collisionElement to measure a wrapper that stays still during the animation. For long lists, memoize the items and keep their handlers stable so that a reorder only moves DOM nodes.

Both demos let the keyboard reorder the focused item with Alt+↑ and Alt+↓.

Auto-scroll direction

CSS decides which axes can scroll. With overflow-x: auto and overflow-y: hidden, only horizontal scrolling is possible. To restrict further, cancel a direction in onDragScroll. Base UI calls the handler once per direction on every scrolling frame:

Horizontal only

<Draggable.Viewport
  onDragScroll={({ direction }, eventDetails) => {
    if (direction === 'vertical') {
      eventDetails.cancel();
    }
  }}
/>

Drag a stop toward the left or right edge and the lane scrolls to follow. It only scrolls sideways, so moving the pointer up or down never scrolls it.

Wake up

Coffee

Standup

Code review

Lunch

Design sync

Focus block

Errands

Gym

Dinner

Reading

Sleep

index.tsx GripIcon.tsx DragPageAutoScroll.tsx axis.module.css

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

import * as React from 'react';
import { GripIcon } from './GripIcon';
import { DragPageAutoScroll } from './DragPageAutoScroll';

import styles from './axis.module.css';

interface Stop {
  id: string;
  label: string;
}

const stopKind = Draggable.createKind<string>('stop');

// Enough stops that the lane overflows its width and is scrollable on mount, so
// dragging toward an edge has somewhere to scroll.
const INITIAL_STOPS: Stop[] = [
  { id: 'wake', label: 'Wake up' },
  { id: 'coffee', label: 'Coffee' },
  { id: 'standup', label: 'Standup' },
  { id: 'review', label: 'Code review' },
  { id: 'lunch', label: 'Lunch' },
  { id: 'design', label: 'Design sync' },
  { id: 'focus', label: 'Focus block' },
  { id: 'errands', label: 'Errands' },
  { id: 'gym', label: 'Gym' },
  { id: 'dinner', label: 'Dinner' },
  { id: 'reading', label: 'Reading' },
  { id: 'sleep', label: 'Sleep' },
];

// Resolve the insertion slot closest to the pointer along the lane. Candidate
// slots sit before the first stop, between consecutive stops (the midpoint of
// each gap), and after the last one.
function resolveDropIndex(track: HTMLElement, clientX: number): number {
  // The dragged stop's preview is a clone injected next to it, and it carries
  // the same `data-stop`. Skip it: it follows the pointer and is not a real slot.
  const stops = Array.from(
    track.querySelectorAll<HTMLElement>('[data-stop]:not([data-drag-preview])'),
  );
  if (stops.length === 0) {
    return 0;
  }

  const slotXs = [stops[0].getBoundingClientRect().left];
  for (let i = 1; i < stops.length; i += 1) {
    const previous = stops[i - 1].getBoundingClientRect();
    const current = stops[i].getBoundingClientRect();
    slotXs.push((previous.right + current.left) / 2);
  }
  slotXs.push(stops[stops.length - 1].getBoundingClientRect().right);

  let index = 0;
  let bestDx = Infinity;
  for (let i = 0; i < slotXs.length; i += 1) {
    const dx = Math.abs(clientX - slotXs[i]);
    if (dx < bestDx) {
      bestDx = dx;
      index = i;
    }
  }
  return index;
}

export default function AxisLane() {
  const [stops, setStops] = React.useState(INITIAL_STOPS);
  const trackRef = React.useRef<HTMLDivElement | null>(null);

  function moveStop(id: string, insertIndex: number) {
    setStops((previous) => {
      const sourceIndex = previous.findIndex((stop) => stop.id === id);
      // Dropping immediately before or after the source position is a no-op.
      if (sourceIndex === -1 || insertIndex === sourceIndex || insertIndex === sourceIndex + 1) {
        return previous;
      }
      const stop = previous[sourceIndex];
      const without = previous.filter((entry) => entry.id !== id);
      // Removing the stop shifts indices above the source down by one.
      const adjusted = sourceIndex < insertIndex ? insertIndex - 1 : insertIndex;
      return [...without.slice(0, adjusted), stop, ...without.slice(adjusted)];
    });
  }

  return (
    <Draggable.Provider>
      <DragPageAutoScroll accept={stopKind} />
      <div className={styles.Root}>
        <p className={styles.Hint}>
          Drag a stop toward the left or right edge and the lane scrolls to follow. It only scrolls
          sideways, so moving the pointer up or down never scrolls it.
        </p>
        <Draggable.Viewport
          onDragScroll={({ direction }, eventDetails) => {
            if (direction !== 'horizontal') {
              eventDetails.cancel();
            }
          }}
          className={styles.Lane}
        >
          <Draggable.Target
            ref={trackRef}
            className={styles.Track}
            accept={stopKind}
            onDraggableDrop={({ source, location }) => {
              const track = trackRef.current;
              if (track) {
                moveStop(source.payload, resolveDropIndex(track, location.current.input.clientX));
              }
            }}
          >
            {stops.map((stop) => (
              <Draggable.Root
                key={stop.id}
                kind={stopKind}
                payload={stop.id}
                data-stop
                className={styles.Stop}
              >
                <GripIcon className={styles.Grip} />
                {stop.label}
              </Draggable.Root>
            ))}
          </Draggable.Target>
        </Draggable.Viewport>
      </div>
    </Draggable.Provider>
  );
}

The handler also receives the drag source, so the allowed direction can depend on what’s being dragged. A grid can scroll vertically for rows and horizontally for columns:

A direction that depends on the item

<Draggable.Viewport
  accept={[row, column]}
  onDragScroll={({ source, direction }, eventDetails) => {
    const allowed = row.matches(source) ? 'vertical' : 'horizontal';
    if (direction !== allowed) {
      eventDetails.cancel();
    }
  }}
/>

Auto-scroll speed

maxSpeed sets the auto-scroll speed reached at the container’s edge, in pixels per second. It defaults to 900. Scrolling accelerates as the pointer approaches the edge. Lower it for a short list or raise it for a large scroll range:

Slower in a short list

<Draggable.Viewport maxSpeed={300} />

It also accepts a function, called on every scrolling frame:

A speed based on the content height

<Draggable.Viewport maxSpeed={({ element }) => Math.min(2400, element.scrollHeight / 4)} />

A maxSpeed of 0 stops the container and lets an ancestor scroll instead, like canceling in onDragScroll.

Auto-scroll outside the viewport

overflowMargin lets scrolling continue when the drag moves outside a container. Pass a distance in CSS pixels for every edge, or an object to extend individual physical edges:

Keep scrolling above and below a calendar

<Draggable.Viewport overflowMargin={{ top: 160, bottom: 160 }} />

The default is 0. Omitted edges, negative values, and non-finite values are treated as 0. With only top and bottom configured, the drag must stay within the viewport’s horizontal bounds. To include the corners, extend the corresponding horizontal edges too:

Extend every edge

<Draggable.Viewport overflowMargin={80} />

Inside the viewport, the edge zones and speed stay the same. Outside an enabled edge, scrolling keeps its maximum engagement and existing speed ramp, up to maxSpeed. It stops beyond the margin. Updating overflowMargin on a mounted Draggable.Viewport takes effect without another pointer move.

Viewports containing the drag position get first use of each scrolling direction. Outside margins then compete for unclaimed directions, innermost first. Scroll limits and onDragScroll’s cancel() and consume() behavior still apply. Drag modifiers participate in deciding which viewport can scroll, just as they do without margins.

The margin changes only auto-scrolling: it does not enlarge drop targets, move the preview, or change the coordinates passed to onDragScroll. It does not change document/page scrolling, which already continues when a captured pointer leaves the window.

Custom auto-scrolling

When Base UI can’t scroll an element itself, for example a canvas panned with a CSS transform, use onDragScroll to apply the movement yourself. The element doesn’t need scrollable overflow. Edge zones, acceleration, and nesting work the same as for a scroll container.

Drag a pin to the bottom edge and hold still. The canvas has nothing to scroll, so it moves its own camera, and the archive scrolls into reach.

API reference

Provider

Groups the drag sources, drop targets, and viewports of an interaction. It provides the default kind used by parts that declare none, and gives custom previews access to React context. Required above the Draggable parts and useDragDropManager. Doesn’t render its own HTML element.

childrenReact.ReactNode—

Name: children
Description: The parts of the interaction.
Type: React.ReactNode | undefined

Draggable.Provider.PropsHide

Re-Export of Provider props as DraggableProviderProps

Root

An element that can be picked up with the pointer and dropped on a matching drop target. While dragging, a clone of the element follows the pointer by default. Renders a <div> element.

activationUnion—

Name: activation
Description: Determines when a pointer press starts a drag. Accepts one activation method for every pointer type, a map with a method per pointer type, or an array to allow several methods. By default, mouse and pen start after 5px of movement, and touch after a 250ms hold.
Type: DragActivationConfig | DragActivationConfig[] | undefined

collisionbooleantrue

Name: collision
Description: Whether other items of the nearest matching collision provider can be dropped on this one.
Type: boolean | undefined
Default: true

collisionElementfunction—

Name: collisionElement
Description: Returns the element measured for collisions, for example a padded row wrapper so that the gaps between items count too. Defaults to the root’s own element.
Type: ((element: HTMLElement) => HTMLElement) | undefined

collisionPayloadTPayload—

Name: collisionPayload
Description: The payload reported by the collision provider when another item is dragged over this one. Defaults to payload.
Type: TPayload | undefined

dragCursorstring | false'grabbing'

Name: dragCursor
Description: The CSS cursor shown across the document during a mouse or pen drag. Pass false to manage the cursor yourself.
Type: string | false | undefined
Default: 'grabbing'

kindUnion—

Name: kind
Description: The kind of this item, created with Draggable.createKind. Defaults to the kind of the nearest <Draggable.Provider>, which carries no payload.
Type: | DragKind<TPayload, TDragData> | DragKind<undefined, TDragData> | undefined

modifiersDragModifiers—

Name: modifiers
Description: One or more modifiers that constrain the drag, applied in order. They affect both the preview and the drop position. See Constraining movement.
Type: DragModifiers | undefined

onBeforeMoveStartfunction—

Name: onBeforeMoveStart
Description: Event handler called just before a drag starts, once the activation threshold is met. Call eventDetails.cancel() to prevent the drag.
Type: | (( context: MoveStartContext<TPayload, TDragData>, eventDetails: BeforeMoveStartEventDetails, ) => void) | (( context: MoveStartContext<undefined, TDragData>, eventDetails: BeforeMoveStartEventDetails, ) => void) | undefined

onMovefunction—

Name: onMove
Description: Event handler called as the pointer moves or a modifier key changes, at most once per animation frame. Use a drop target’s onDraggableMove for hover feedback.
Type: | (( parameters: MoveEvent<TPayload, TDragData>, eventDetails: MoveEventDetails, ) => void) | (( parameters: MoveEvent<undefined, TDragData>, eventDetails: MoveEventDetails, ) => void) | undefined

onMoveEndfunction—

Name: onMoveEnd
Description: Event handler called once when the drag ends, after a drop, a release outside any target, or a cancellation. eventDetails.reason is 'drop' for a successful drop.

A drag canceled during pickup fires this handler without a preceding onMoveStart.
Type: | (( parameters: MoveEndEvent<TPayload, TDragData>, eventDetails: MoveEndEventDetails, ) => void) | (( parameters: MoveEndEvent<undefined, TDragData>, eventDetails: MoveEndEventDetails, ) => void) | undefined

onMoveStartfunction—

Name: onMoveStart
Description: Event handler called once when the drag starts. The preview exists by then, so the source can be measured or restyled safely.
Type: | (( parameters: MoveStartEvent<TPayload, TDragData>, eventDetails: MoveStartEventDetails, ) => void) | (( parameters: MoveStartEvent<undefined, TDragData>, eventDetails: MoveStartEventDetails, ) => void) | undefined

onTargetChangefunction—

Name: onTargetChange
Description: Event handler called when the drop targets under the pointer change.
Type: | (( parameters: DropTargetChangeEvent< TPayload, TDragData >, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: DropTargetChangeEvent< undefined, TDragData >, eventDetails: DropTargetChangeEventDetails, ) => void) | undefined

payloadTPayload—

Name: payload
Type: TPayload | undefined

previewKeystring | number—

Name: previewKey
Description: A stable key that lets the settling preview find this item again after it remounts, for example when a virtualized or reordered list recreates it. Use the same key for the same item.
Type: string | number | undefined

snapUnion—

Name: snap
Description: Divides this item into equal steps for getSnappedLocalPoint() when another item is dragged over it. Accepts step counts or a function returning them. Doesn’t affect the preview’s position.
Type: | DragSnapSteps | (( context: DropTargetResolutionContext< TPayload, TDragData >, ) => DragSnapSteps | undefined) | (( context: DropTargetResolutionContext< undefined, TDragData >, ) => DragSnapSteps | undefined) | undefined

disabledbooleanfalse

Name: disabled
Description: Whether dragging is disabled. Pointer presses keep their normal behavior. Use onBeforeMoveStart 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-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-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.

Draggable.Root.PropsHide

Re-Export of Root props as DraggableRootProps

Draggable.Root.StateHide

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

Draggable.Root.BeforeMoveStartEventHide

type DraggableRootBeforeMoveStartEvent<TPayload = unknown, TDragData = unknown> = {
  /**
   * The source being picked up. The same record is used if the drag starts.
   * Call `updateDragData` to initialize gesture data before targets resolve and previews render.
   * A canceled pickup does not carry its gesture data into the next attempt.
   */
  source: DragSource<TPayload, TDragData>;
  /** 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;
}

Draggable.Root.BeforeMoveStartEventDetailsHide

type DraggableRootBeforeMoveStartEventDetails = (
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }
) & {
  /** 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;
}

Draggable.Root.BeforeMoveStartEventReasonHide

type DraggableRootBeforeMoveStartEventReason = 'pointer' | 'double-click'

Draggable.Root.MoveEndEventHide

type DraggableRootMoveEndEvent<TPayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
  /**
   * Whether the drag was canceled rather than released. A release outside any drop
   * target isn't a cancellation. Read `eventDetails.reason` for the exact outcome.
   */
  canceled: boolean;
  /**
   * The drop target that received the drop, or `null` when the drag was released
   * outside any target or canceled.
   */
  dropTarget: DropTargetRecord | null;
}

Draggable.Root.MoveEndEventDetailsHide

type DraggableRootMoveEndEventDetails =
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | MouseEvent }
  | { reason: 'outside-release'; event: PointerEvent | MouseEvent }
  | { 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 }

Draggable.Root.MoveEndEventReasonHide

type DraggableRootMoveEndEventReason =
  | 'escape-key'
  | 'tab-key'
  | 'drop'
  | 'outside-release'
  | 'imperative-action'
  | 'window-blur'
  | 'page-hidden'
  | 'pointer-canceled'
  | 'capture-lost'
  | 'missed-release'
  | 'document-detached'
  | 'handler-error'

Draggable.Root.MoveEventHide

type DraggableRootMoveEvent<TPayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
}

Draggable.Root.MoveEventDetailsHide

type DraggableRootMoveEventDetails =
  { reason: 'pointer'; event: PointerEvent } | { reason: 'modifier-key'; event: KeyboardEvent }

Draggable.Root.MoveEventReasonHide

type DraggableRootMoveEventReason = 'pointer' | 'modifier-key'

Draggable.Root.MoveStartEventHide

type DraggableRootMoveStartEvent<TPayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
}

Draggable.Root.MoveStartEventDetailsHide

type DraggableRootMoveStartEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }

Draggable.Root.MoveStartEventReasonHide

type DraggableRootMoveStartEventReason = 'pointer' | 'double-click'

Draggable.Root.PropsWithPayloadHide

type DraggableRootPropsWithPayload<TPayload, TDragData = unknown> = {
  /**
   * 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);
  /**
   * A stable key that lets the settling preview find this item again after it remounts,
   * for example when a virtualized or reordered list recreates it.
   * Use the same key for the same item.
   */
  previewKey?: string | number;
  /**
   * Whether dragging is disabled. Pointer presses keep their normal behavior.
   * Use `onBeforeMoveStart` when the decision depends on the gesture.
   * @default false
   */
  disabled?: boolean;
  /**
   * Event handler called just before a drag starts, once the activation threshold is met.
   * Call `eventDetails.cancel()` to prevent the drag.
   */
  onBeforeMoveStart?: (
    context: MoveStartContext<TPayload, TDragData>,
    eventDetails: BeforeMoveStartEventDetails,
  ) => void;
  /**
   * Determines when a pointer press starts a drag. Accepts one activation method for
   * every pointer type, a map with a method per pointer type, or an array to allow
   * several methods. By default, mouse and pen start after 5px of movement, and touch
   * after a 250ms hold.
   */
  activation?: DragActivationConfig | DragActivationConfig[];
  /**
   * One or more modifiers that constrain the drag, applied in order.
   * They affect both the preview and the drop position.
   * See [Constraining movement](https://base-ui.com/react/utils/draggable#constraining-movement).
   */
  modifiers?: DragModifiers;
  /**
   * The CSS cursor shown across the document during a mouse or pen drag.
   * Pass `false` to manage the cursor yourself.
   * @default 'grabbing'
   */
  dragCursor?: string | false;
  /**
   * Event handler called once when the drag starts. The preview exists by then,
   * so the source can be measured or restyled safely.
   */
  onMoveStart?: (
    parameters: MoveStartEvent<TPayload, TDragData>,
    eventDetails: MoveStartEventDetails,
  ) => void;
  /**
   * Event handler called as the pointer moves or a modifier key changes,
   * at most once per animation frame. Use a drop target's `onDraggableMove`
   * for hover feedback.
   */
  onMove?: (parameters: MoveEvent<TPayload, TDragData>, eventDetails: MoveEventDetails) => void;
  /** Event handler called when the drop targets under the pointer change. */
  onTargetChange?: (
    parameters: DropTargetChangeEvent<TPayload, TDragData>,
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called once when the drag ends, after a drop, a release outside any
   * target, or a cancellation. `eventDetails.reason` is `'drop'` for a successful drop.
   *
   * A drag canceled during pickup fires this handler without a preceding `onMoveStart`.
   */
  onMoveEnd?: (
    parameters: MoveEndEvent<TPayload, TDragData>,
    eventDetails: MoveEndEventDetails,
  ) => void;
  children?: React.ReactNode;
  /**
   * Whether other items of the nearest matching collision provider can be dropped on this one.
   * @default true
   */
  collision?: boolean;
  /**
   * Divides this item into equal steps for `getSnappedLocalPoint()` when another item
   * is dragged over it. Accepts step counts or a function returning them.
   * Doesn't affect the preview's position.
   */
  snap?:
    | DragSnapSteps
    | ((context: DropTargetResolutionContext<TPayload, TDragData>) => DragSnapSteps | undefined);
  /**
   * The payload reported by the collision provider when another item is dragged over this one.
   * Defaults to `payload`.
   */
  collisionPayload?: TPayload;
  /**
   * Returns the element measured for collisions, for example a padded row wrapper
   * so that the gaps between items count too. Defaults to the root's own element.
   */
  collisionElement?: (element: HTMLElement) => HTMLElement;
  kind: DragKind<TPayload, TDragData>;
  payload: TPayload;
}

Draggable.Root.TargetChangeEventHide

type DraggableRootTargetChangeEvent<TPayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
}

Draggable.Root.TargetChangeEventDetailsHide

type DraggableRootTargetChangeEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }
  | { reason: 'modifier-key'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | MouseEvent }
  | { reason: 'outside-release'; event: PointerEvent | MouseEvent }
  | { 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 }

Draggable.Root.TargetChangeEventReasonHide

type DraggableRootTargetChangeEventReason =
  | 'pointer'
  | 'double-click'
  | 'modifier-key'
  | 'escape-key'
  | 'tab-key'
  | 'drop'
  | 'outside-release'
  | 'imperative-action'
  | 'window-blur'
  | 'page-hidden'
  | 'pointer-canceled'
  | 'capture-lost'
  | 'missed-release'
  | 'document-detached'
  | 'handler-error'

Handle

The area of a draggable that starts a drag. The rest of the draggable stays interactive. Omit it to make the whole draggable start a drag. Renders a <span> element.

disabledundefined—

Name: disabled
Description: Not supported. A handle follows the disabled state of its <Draggable.Root>.
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;
}

Preview

Configures what follows the pointer during a drag. Without children, it configures the default clone of the source and renders nothing. With children, it renders them in a <div> element inserted beside the source while dragging. That element reads React context from above the nearest <Draggable.Provider>.

kindDragKind<TPayload, TDragData>—

Name: kind
Description: The kind of the dragged item, which types source.payload in the render function. Drags of other kinds show no preview.
Type: DragKind<TPayload, TDragData> | undefined

modifiersDragModifiers—

Name: modifiers
Description: One or more modifiers that constrain the preview only. The drop position still follows the pointer. To constrain the drag itself, use modifiers on Draggable.Root.
Type: DragModifiers | undefined

offsetDragPreviewOffset'source'

Name: offset
Description: Where the preview sits relative to the pointer.
Type: DragPreviewOffset | undefined
Default: 'source'

containerDragPreviewContainer—

Name: container
Description: Where to insert the preview element in the DOM. Defaults to beside the source, so the same CSS applies to it. Pass a container to keep selectors such as :last-child on the source’s siblings unchanged during the drag.
Type: DragPreviewContainer | undefined

disabledbooleanfalse

Name: disabled
Description: Whether to show no preview. The drag still runs.
Type: boolean | undefined
Default: false

children

| React.ReactNode 
|  ((parameters: DragPreviewRenderEvent<TPayload, TDragData>) => React.ReactNode) 
|  ((parameters: DragPreviewRenderEvent) => React.ReactNode)

—

Name: children
Description: The preview content. Pass a function to build the content from the drag source when the drag starts. It can return null to show no preview for that drag.
Type: | React.ReactNode | (( parameters: DragPreviewRenderEvent< TPayload, TDragData >, ) => 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-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-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 = {}

Draggable.Preview.RenderEventHide

type DraggablePreviewRenderEvent<TPayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
}

Target

An area where a matching draggable can be dropped. Renders a <div> element.

acceptUnion—

Name: accept
Type: | DragAccept<undefined, unknown> | NonNullable< | DragAccept<TSourcePayload, TSourceDragData> | undefined > | NonNullable< | DragAccept<TPayload | unknown, TDragData | unknown> | undefined > | DragAcceptedKind | DragAcceptedKind[] | undefined

canDropfunction—

Name: canDrop
Description: Decides whether the current drag can be dropped on this target. Runs after accept.

Return false to skip this target and let an ancestor receive the drop. Return 'reject' to block the drop on this target, its nested targets, and its ancestors, for example when a column is full. The target then has [data-rejected].
Type: | (( parameters: DropTargetResolutionContext< undefined, unknown >, ) => boolean | 'reject') | (( parameters: DropTargetResolutionContext< TSourcePayload, TSourceDragData >, ) => boolean | 'reject') | (( parameters: DropTargetResolutionContext< TPayload | unknown, TDragData | unknown >, ) => boolean | 'reject') | undefined

kindUnion—

Name: kind
Description: The kind of this target, created with Draggable.createKind. Use its matches method to tell target kinds apart in a shared handler, which also types target.payload. Not to be confused with accept, which lists the kinds of draggable this target takes.
Type: | DragKind<undefined, TTargetDragData> | DragKind<TTargetPayload, TTargetDragData> | DragKind<TTargetPayload, unknown> | undefined

onDraggableDropfunction—

Name: onDraggableDrop
Description: Event handler called when the drag is released over this target. Only the innermost target under the pointer receives it, and it never fires on a cancel. Use the source’s or a monitor’s onMoveEnd to observe every drag end.
Type: | (( parameters: DropEvent< undefined, undefined, unknown, TTargetDragData >, eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent; }, ) => void) | (( parameters: DropEvent< TSourcePayload, TTargetPayload, TSourceDragData, TTargetDragData >, eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent; }, ) => void) | (( parameters: DropEvent< TSourcePayload, undefined, TSourceDragData, TTargetDragData >, eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent; }, ) => void) | (( parameters: DropEvent< TPayload | unknown, TTargetPayload, TDragData | unknown, unknown >, eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent; }, ) => void) | (( parameters: DropEvent< TPayload | unknown, TTargetPayload, TDragData | unknown, TTargetDragData >, eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent; }, ) => void) | (( parameters: DropEvent< TPayload | unknown, undefined, TDragData | unknown, TTargetDragData >, eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent; }, ) => void) | undefined

onDraggableEnterfunction—

Name: onDraggableEnter
Description: Event handler called when the drag moves over this target.
Type: | (( parameters: { location: DragLocationHistory; source: DragSource<undefined, unknown>; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource<TSourcePayload, TSourceDragData>; target: DropTargetRecord< TTargetPayload, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource<TSourcePayload, TSourceDragData>; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord<TTargetPayload, unknown>; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord< TTargetPayload, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | undefined

onDraggableLeavefunction—

Name: onDraggableLeave
Description: Event handler called when the drag moves off this target, or ends. eventDetails.reason tells which.
Type: | (( parameters: { location: DragLocationHistory; source: DragSource<undefined, unknown>; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource<TSourcePayload, TSourceDragData>; target: DropTargetRecord< TTargetPayload, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource<TSourcePayload, TSourceDragData>; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord<TTargetPayload, unknown>; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord< TTargetPayload, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: DropTargetChangeEventDetails, ) => void) | undefined

onDraggableMovefunction—

Name: onDraggableMove
Description: Event handler called on every animation frame the pointer moves or a modifier key changes while the drag is over this target, starting with the frame it enters. Put hover feedback such as drop indicators here.
Type: | (( parameters: { location: DragLocationHistory; source: DragSource<undefined, unknown>; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: MoveEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource<TSourcePayload, TSourceDragData>; target: DropTargetRecord< TTargetPayload, TTargetDragData >; }, eventDetails: MoveEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource<TSourcePayload, TSourceDragData>; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: MoveEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord<TTargetPayload, unknown>; }, eventDetails: MoveEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord< TTargetPayload, TTargetDragData >; }, eventDetails: MoveEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: MoveEventDetails, ) => void) | undefined

onDraggableStartfunction—

Name: onDraggableStart
Description: Event handler called when a drag starts while this target is already under the pointer. Use a monitor’s onMoveStart to observe drags starting elsewhere.
Type: | (( parameters: { location: DragLocationHistory; source: DragSource<undefined, unknown>; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: MoveStartEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource<TSourcePayload, TSourceDragData>; target: DropTargetRecord< TTargetPayload, TTargetDragData >; }, eventDetails: MoveStartEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource<TSourcePayload, TSourceDragData>; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: MoveStartEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord<TTargetPayload, unknown>; }, eventDetails: MoveStartEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord< TTargetPayload, TTargetDragData >; }, eventDetails: MoveStartEventDetails, ) => void) | (( parameters: { location: DragLocationHistory; source: DragSource< TPayload | unknown, TDragData | unknown >; target: DropTargetRecord< undefined, TTargetDragData >; }, eventDetails: MoveStartEventDetails, ) => void) | undefined

payloadTTargetPayload—

Name: payload
Type: TTargetPayload | undefined

snapUnion—

Name: snap
Description: Divides the target into equal steps for getSnappedLocalPoint(). For example, { y: 96 } splits a day column into 15-minute slots, whatever its height. Accepts step counts or a function receiving the drag source.

It only changes the value this target reports. Use the snapToGrid modifier to snap the preview itself.
Type: | DragSnapSteps | (( context: DropTargetResolutionContext< undefined, unknown >, ) => DragSnapSteps | undefined) | (( context: DropTargetResolutionContext< TSourcePayload, TSourceDragData >, ) => DragSnapSteps | undefined) | (( context: DropTargetResolutionContext< TPayload | unknown, TDragData | unknown >, ) => DragSnapSteps | undefined) | undefined

trackDragOverbooleantrue

Name: trackDragOver
Description: Whether to track the drag-over state and expose it through data attributes. Disable it on targets that don’t use them to avoid re-rendering as the drag moves.
Type: boolean | undefined
Default: true

disabledbooleanfalse

Name: disabled
Description: Whether the target ignores drags. A disabled target is skipped, so drags fall through to ancestor targets.
Type: boolean | undefined
Default: false

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.Target.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.Target.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.Target.State, ) => ReactElement) | undefined

data-disabled

Present while the drop target is disabled.

data-accepting

Present while a drag this target accepts is active, regardless of pointer position. Use it to highlight every compatible drop target. Absent when trackDragOver is false.

data-drag-over

Present while a matching drag source is over the target or a nested descendant. Absent when trackDragOver is false.

data-drag-over-innermost

Present while the target is the innermost one under the source. Absent when trackDragOver is false.

data-drop-target

Present while the element is registered as a drop target. Base UI also uses it to resolve targets during hit testing.

data-rejected

Present while canDrop returns 'reject' for the current position. Use it to display feedback such as a full column. Absent when trackDragOver is false.

Attribute	Description	-
`data-disabled`	Present while the drop target is disabled.
`data-accepting`	Present while a drag this target accepts is active, regardless of pointer position. Use it to highlight every compatible drop target. Absent when `trackDragOver` is `false`.
`data-drag-over`	Present while a matching drag source is over the target or a nested descendant. Absent when `trackDragOver` is `false`.
`data-drag-over-innermost`	Present while the target is the innermost one under the source. Absent when `trackDragOver` is `false`.
`data-drop-target`	Present while the element is registered as a drop target. Base UI also uses it to resolve targets during hit testing.
`data-rejected`	Present while `canDrop` returns `'reject'` for the current position. Use it to display feedback such as a full column. Absent when `trackDragOver` is `false`.

Draggable.Target.PropsHide

Re-Export of Target props as DraggableTargetProps

Draggable.Target.StateHide

type DraggableTargetState = {
  /**
   * Whether a matching drag is over this target or one of its nested targets.
   * Always `false` when `trackDragOver` is `false`.
   */
  dragOver: boolean;
  /**
   * Whether this target accepts the drag in progress, regardless of the pointer position.
   * Based on `accept` alone, so `canDrop` can still refuse the drop.
   * Always `false` when `trackDragOver` is `false`.
   */
  accepting: boolean;
  /**
   * Whether this is the innermost target under the pointer, the one that would receive the drop.
   * Always `false` when `trackDragOver` is `false`.
   */
  dragOverInnermost: boolean;
  /**
   * Whether `canDrop` returned `'reject'` for the current position.
   * Always `false` when `trackDragOver` is `false`.
   */
  rejected: boolean;
  /** Whether the drop target is disabled. */
  disabled: boolean;
}

Draggable.Target.DropEventHide

type DraggableTargetDropEvent<
  TSourcePayload = unknown,
  TTargetPayload = unknown,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The drop target's own record. */
  target: DropTargetRecord<TTargetPayload, TTargetDragData>;
  dropTarget: DropTargetRecord<TTargetPayload, TTargetDragData>;
}

Draggable.Target.DropEventDetailsHide

type DraggableTargetDropEventDetails = {
  /** Why the event fired. */
  reason: 'drop';
  /**
   * The native event. Reasons that don't come from a native event, such as
   * `'imperative-action'`, carry a generic `Event`.
   */
  event: PointerEvent | MouseEvent;
}

Draggable.Target.DropEventReasonHide

type DraggableTargetDropEventReason = 'drop'

Draggable.Target.EnterEventHide

type DraggableTargetEnterEvent<
  TSourcePayload = unknown,
  TTargetPayload = unknown,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /** The drop target's own record. */
  target: DropTargetRecord<TTargetPayload, TTargetDragData>;
}

Draggable.Target.EnterEventDetailsHide

type DraggableTargetEnterEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }
  | { reason: 'modifier-key'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | MouseEvent }
  | { reason: 'outside-release'; event: PointerEvent | MouseEvent }
  | { 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 }

Draggable.Target.EnterEventReasonHide

type DraggableTargetEnterEventReason =
  | 'pointer'
  | 'double-click'
  | 'modifier-key'
  | 'escape-key'
  | 'tab-key'
  | 'drop'
  | 'outside-release'
  | 'imperative-action'
  | 'window-blur'
  | 'page-hidden'
  | 'pointer-canceled'
  | 'capture-lost'
  | 'missed-release'
  | 'document-detached'
  | 'handler-error'

Draggable.Target.LeaveEventHide

type DraggableTargetLeaveEvent<
  TSourcePayload = unknown,
  TTargetPayload = unknown,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /** The drop target's own record. */
  target: DropTargetRecord<TTargetPayload, TTargetDragData>;
}

Draggable.Target.LeaveEventDetailsHide

type DraggableTargetLeaveEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }
  | { reason: 'modifier-key'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | MouseEvent }
  | { reason: 'outside-release'; event: PointerEvent | MouseEvent }
  | { 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 }

Draggable.Target.LeaveEventReasonHide

type DraggableTargetLeaveEventReason =
  | 'pointer'
  | 'double-click'
  | 'modifier-key'
  | 'escape-key'
  | 'tab-key'
  | 'drop'
  | 'outside-release'
  | 'imperative-action'
  | 'window-blur'
  | 'page-hidden'
  | 'pointer-canceled'
  | 'capture-lost'
  | 'missed-release'
  | 'document-detached'
  | 'handler-error'

Draggable.Target.MoveEventHide

type DraggableTargetMoveEvent<
  TSourcePayload = unknown,
  TTargetPayload = unknown,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /** The drop target's own record. */
  target: DropTargetRecord<TTargetPayload, TTargetDragData>;
}

Draggable.Target.MoveEventDetailsHide

type DraggableTargetMoveEventDetails =
  { reason: 'pointer'; event: PointerEvent } | { reason: 'modifier-key'; event: KeyboardEvent }

Draggable.Target.MoveEventReasonHide

type DraggableTargetMoveEventReason = 'pointer' | 'modifier-key'

Draggable.Target.PropsWithPayloadHide

type DraggableTargetPropsWithPayload<
  TSourcePayload,
  TTargetPayload,
  TSourceDragData = unknown,
  TTargetDragData = unknown,
> = {
  /**
   * CSS class applied to the element, or a function that
   * returns a class based on the component's state.
   */
  className?: string | ((state: Draggable.Target.State) => string | 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.Target.State) => ReactElement);
  /**
   * Style applied to the element, or a function that
   * returns a style object based on the component's state.
   */
  style?:
    React.CSSProperties | ((state: Draggable.Target.State) => React.CSSProperties | undefined);
  /**
   * The kind of this target, created with `Draggable.createKind`. Use its `matches`
   * method to tell target kinds apart in a shared handler, which also types
   * `target.payload`. Not to be confused with `accept`, which lists the kinds of
   * draggable this target takes.
   */
  kind?: DragKind<TTargetPayload, TTargetDragData>;
  /**
   * Whether the target ignores drags. A disabled target is skipped, so drags fall
   * through to ancestor targets.
   * @default false
   */
  disabled?: boolean;
  /**
   * Divides the target into equal steps for `getSnappedLocalPoint()`. For example,
   * `{ y: 96 }` splits a day column into 15-minute slots, whatever its height.
   * Accepts step counts or a function receiving the drag source.
   *
   * It only changes the value this target reports. Use the `snapToGrid` modifier
   * to snap the preview itself.
   */
  snap?:
    | DragSnapSteps
    | ((
        context: DropTargetResolutionContext<TSourcePayload, TSourceDragData>,
      ) => DragSnapSteps | undefined);
  /**
   * Event handler called when the drag is released over this target. Only the innermost
   * target under the pointer receives it, and it never fires on a cancel.
   * Use the source's or a monitor's `onMoveEnd` to observe every drag end.
   */
  onDraggableDrop?: (
    parameters: DropEvent<TSourcePayload, TTargetPayload, TSourceDragData, TTargetDragData>,
    eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent },
  ) => void;
  /**
   * Event handler called when a drag starts while this target is already under the
   * pointer. Use a monitor's `onMoveStart` to observe drags starting elsewhere.
   */
  onDraggableStart?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TSourceDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: MoveStartEventDetails,
  ) => void;
  /**
   * Event handler called on every animation frame the pointer moves or a modifier key
   * changes while the drag is over this target, starting with the frame it enters.
   * Put hover feedback such as drop indicators here.
   */
  onDraggableMove?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TSourceDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: MoveEventDetails,
  ) => void;
  /** Event handler called when the drag moves over this target. */
  onDraggableEnter?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TSourceDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called when the drag moves off this target, or ends.
   * `eventDetails.reason` tells which.
   */
  onDraggableLeave?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TSourceDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * One or more kinds of draggable this target accepts. Pass `Draggable.anyKind`
   * to accept every drag, with `source.payload` typed as `unknown`.
   *
   * Drags of other kinds ignore this target, but an ancestor target can still accept them.
   */
  accept: NonNullable<DragAccept<TSourcePayload, TSourceDragData> | undefined>;
  /**
   * Decides whether the current drag can be dropped on this target. Runs after `accept`.
   *
   * Return `false` to skip this target and let an ancestor receive the drop.
   * Return `'reject'` to block the drop on this target, its nested targets, and its
   * ancestors, for example when a column is full. The target then has `[data-rejected]`.
   */
  canDrop?: (
    parameters: DropTargetResolutionContext<TSourcePayload, TSourceDragData>,
  ) => boolean | 'reject';
  /**
   * Whether to track the drag-over state and expose it through data attributes.
   * Disable it on targets that don't use them to avoid re-rendering as the drag moves.
   * @default true
   */
  trackDragOver?: boolean;
  payload: TTargetPayload;
}

Draggable.Target.StartEventHide

type DraggableTargetStartEvent<
  TSourcePayload = unknown,
  TTargetPayload = unknown,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /** The drop target's own record. */
  target: DropTargetRecord<TTargetPayload, TTargetDragData>;
}

Draggable.Target.StartEventDetailsHide

type DraggableTargetStartEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }

Draggable.Target.StartEventReasonHide

type DraggableTargetStartEventReason = 'pointer' | 'double-click'

Viewport

A scroll container that scrolls automatically when a drag nears its edges. Each container, including nested ones, needs its own viewport. Renders a <div> element.

acceptUnion—

Name: accept
Description: One or more kinds of draggable that scroll this container. Omit it to scroll for every drag.
Type: | DragAccept<TSourcePayload, TDragData> | DragAccept<TPayload | unknown, TDragData | unknown> | DragAcceptedKind | DragAcceptedKind[] | undefined

maxSpeedUnion900

Name: maxSpeed
Description: The scrolling speed reached at the container’s edge, in pixels per second. Accepts a number or a function called on every scrolling frame. 0 stops this container and lets an ancestor viewport scroll instead.
Type: | number | (( parameters: DragAutoScrollFrameContext< TSourcePayload, TDragData >, ) => number) | (( parameters: DragAutoScrollFrameContext< TPayload | unknown, TDragData | unknown >, ) => number) | undefined
Default: 900

onDragScrollfunction—

Name: onDragScroll
Description: Event handler called once per direction on every scrolling frame. Call eventDetails.cancel() to prevent scrolling in that direction, or to apply the movement yourself for an element Base UI can’t scroll, such as a panned canvas. After moving, call eventDetails.consume() to keep an ancestor viewport from scrolling on the same axis. Skip it at a bound the element can’t move past.
Type: | DragAutoScrollHandler<TSourcePayload, TDragData> | DragAutoScrollHandler< TPayload | unknown, TDragData | unknown > | undefined

overflowMarginAutoScrollOverflowMargin0

Name: overflowMargin
Description: How far outside the container a drag can continue auto-scrolling, in CSS pixels. A number applies to every edge; an object sets physical edges independently. Omitted, negative, and non-finite edge values are treated as 0. Outside an edge, scrolling keeps its maximum engagement and existing speed ramp. Viewports containing the drag position take priority over outside margins. Does not change drop targets, layout, or document/page scrolling.
Type: AutoScrollOverflowMargin | undefined
Default: 0

disabledbooleanfalse

Name: disabled
Description: Whether auto-scrolling is disabled. An ancestor viewport can then scroll instead. Changing it during a drag pauses or resumes scrolling. Use onDragScroll for a decision that depends on the drag.
Type: boolean | undefined
Default: false

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.Viewport.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.Viewport.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.Viewport.State, ) => ReactElement) | undefined

data-disabled

Present while auto-scrolling is disabled.

Attribute	Description	-
`data-disabled`	Present while auto-scrolling is disabled.

Draggable.Viewport.PropsHide

Re-Export of Viewport props as DraggableViewportProps

Draggable.Viewport.StateHide

type DraggableViewportState = {
  /** Whether auto-scrolling is disabled. */
  disabled: boolean;
}

Draggable.Viewport.DragScrollEventHide

type DraggableViewportDragScrollEvent<TPayload = unknown, TDragData = unknown> = {
  /**
   * How far to move horizontally this frame, in CSS pixels, with `scrollBy`
   * semantics: a positive value moves the view right, so the content slides left
   * under the pointer. Apply this delta as-is, without multiplying by elapsed time.
   * `0` when the horizontal axis isn't engaged this frame.
   */
  x: number;
  /** How far to move vertically this frame, in CSS pixels. A positive value moves the view down. */
  y: number;
  direction: DragAutoScrollDirection;
  /**
   * The position used to determine scrolling. It may differ from the modified
   * drag position when a modifier separates that position from the pointer.
   */
  input: DragInput;
  source: DragSource<TPayload, TDragData>;
  element: HTMLElement;
}

Draggable.Viewport.DragScrollEventDetailsHide

type DraggableViewportDragScrollEventDetails = {
  /** Why the frame ran. Always `'pointer'`: the loop follows the pointer's position. */
  reason: 'pointer';
  /** A generic `Event`, rather than the native pointer event. */
  event: Event;
  /** Prevents Base UI from scrolling the container in this direction. */
  cancel: () => void;
  /** Whether `cancel` has been called. */
  isCanceled: boolean;
  /**
   * Claims this direction, so that ancestor viewports don't scroll on the same axis.
   * Skip it at a bound the element can't move past, so an ancestor can scroll instead.
   */
  consume: () => void;
  /** Whether `consume` has been called. */
  isConsumed: boolean;
}

Draggable.Viewport.DragScrollEventReasonHide

type DraggableViewportDragScrollEventReason = 'pointer'

CollisionProvider

Groups draggables of the same kind and reports which one is under the pointer, for sorting. Doesn’t render its own HTML element.

canCollidefunction—

Name: canCollide
Description: Whether the dragged item can be dropped on a given item of this group. Return false to skip the item, or 'reject' to block the drop.
Type: | ((context: { source: DragSource<TPayload, TDragData>; target: TPayload; }) => boolean | 'reject') | undefined

kind^*DragKind<TPayload, TDragData>—

Name: kind
Description: The kind of the items in this group. Pass the same kind to each <Draggable.Root>.
Type: DragKind<TPayload, TDragData>

onCollisionChangefunction—

Name: onCollisionChange
Description: Event handler called when the item under the pointer changes, including when the pointer leaves the group. Compare collision with previousCollision to skip updates when the insertion position hasn’t changed.
Type: | (( event: DraggableCollisionEvent<TPayload, TDragData>, details: DropTargetChangeEventDetails, ) => void) | undefined

onMoveEndfunction—

Name: onMoveEnd
Description: Event handler called when a drag that involved this group ends. Use collision to apply the final position, or canceled to restore the original order.
Type: | (( event: DraggableCollisionEndEvent< TPayload, TDragData >, details: MoveEndEventDetails, ) => void) | undefined

onMoveStartfunction—

Name: onMoveStart
Description: Event handler called when an item of this group starts dragging, or when a drag that started elsewhere first enters the group.
Type: | (( event: BaseDragEvent<TPayload, TDragData>, details: MoveStartEventDetails, ) => void) | undefined

childrenReact.ReactNode—

Name: children
Type: React.ReactNode | undefined

Draggable.CollisionProvider.PropsHide

Re-Export of CollisionProvider props as DraggableCollisionProviderProps

Draggable.CollisionProvider.CollisionHide

type DraggableCollisionProviderCollision<TPayload = unknown, TDragData = unknown> = {
  /**
   * The item under the pointer. Use `payload` to identify it, and `getLocalPoint()`
   * or `getSnappedLocalPoint()` to decide on which side of it to insert.
   */
  target: DropTargetRecord<TPayload, TDragData>;
}

Draggable.CollisionProvider.CollisionChangeEventHide

type DraggableCollisionProviderCollisionChangeEvent<TPayload = unknown, TDragData = unknown> = {
  /** The item under the pointer, or `null` when outside the group or over the dragged item. */
  collision: DraggableCollision<TPayload, TDragData> | null;
  /** The collision reported by the previous `onCollisionChange` call, or `null` before the first. */
  previousCollision: DraggableCollision<TPayload, TDragData> | null;
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
}

Draggable.CollisionProvider.CollisionChangeEventDetailsHide

type DraggableCollisionProviderCollisionChangeEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }
  | { reason: 'modifier-key'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | MouseEvent }
  | { reason: 'outside-release'; event: PointerEvent | MouseEvent }
  | { 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 }

Draggable.CollisionProvider.CollisionChangeEventReasonHide

type DraggableCollisionProviderCollisionChangeEventReason =
  | 'pointer'
  | 'double-click'
  | 'modifier-key'
  | 'escape-key'
  | 'tab-key'
  | 'drop'
  | 'outside-release'
  | 'imperative-action'
  | 'window-blur'
  | 'page-hidden'
  | 'pointer-canceled'
  | 'capture-lost'
  | 'missed-release'
  | 'document-detached'
  | 'handler-error'

Draggable.CollisionProvider.CollisionEventHide

type DraggableCollisionProviderCollisionEvent<TPayload = unknown, TDragData = unknown> = {
  /** The item under the pointer, or `null` when outside the group or over the dragged item. */
  collision: DraggableCollision<TPayload, TDragData> | null;
  /** The collision reported by the previous `onCollisionChange` call, or `null` before the first. */
  previousCollision: DraggableCollision<TPayload, TDragData> | null;
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
}

Draggable.CollisionProvider.MoveEndEventHide

type DraggableCollisionProviderMoveEndEvent<TPayload = unknown, TDragData = unknown> = {
  /**
   * The item under the pointer at release, or `null` when the drag was canceled,
   * released outside the group, or released over the dragged item.
   */
  collision: DraggableCollision<TPayload, TDragData> | null;
  /** The collision reported by the previous `onCollisionChange` call, or `null` before the first. */
  previousCollision: DraggableCollision<TPayload, TDragData> | null;
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
  /**
   * Whether the drag was canceled rather than released. A release outside any drop
   * target isn't a cancellation. Read `eventDetails.reason` for the exact outcome.
   */
  canceled: boolean;
  /**
   * The drop target that received the drop, or `null` when the drag was released
   * outside any target or canceled.
   */
  dropTarget: DropTargetRecord | null;
}

Draggable.CollisionProvider.MoveEndEventDetailsHide

type DraggableCollisionProviderMoveEndEventDetails =
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | MouseEvent }
  | { reason: 'outside-release'; event: PointerEvent | MouseEvent }
  | { 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 }

Draggable.CollisionProvider.MoveEndEventReasonHide

type DraggableCollisionProviderMoveEndEventReason =
  | 'escape-key'
  | 'tab-key'
  | 'drop'
  | 'outside-release'
  | 'imperative-action'
  | 'window-blur'
  | 'page-hidden'
  | 'pointer-canceled'
  | 'capture-lost'
  | 'missed-release'
  | 'document-detached'
  | 'handler-error'

Draggable.CollisionProvider.MoveStartEventHide

type DraggableCollisionProviderMoveStartEvent<TPayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
}

Draggable.CollisionProvider.MoveStartEventDetailsHide

type DraggableCollisionProviderMoveStartEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }

Draggable.CollisionProvider.MoveStartEventReasonHide

type DraggableCollisionProviderMoveStartEventReason = 'pointer' | 'double-click'

createKind

Creates a kind to pass to a draggable’s kind prop and to a target’s accept prop.

Parameters

name^*string—

Name: name
Type: string

Return value

DragKind<TPayload, TDragData>

createGlobalKind

createKind matches kinds by identity: a target accepts a source only if both were given the same kind object, usually a constant they both import. That’s impossible when the source and the target live in code that doesn’t share modules, for example a plugin loaded at runtime, a micro-frontend, or two copies of the same package on one page. createGlobalKind solves this by using a string key as the identity. Two calls with the same key, from anywhere on the page, produce kinds that match each other:

The same kind declared in two separate bundles

// In the host application
const card = Draggable.createGlobalKind<CardPayload>('myapp/card');

// In a plugin bundled separately
const card = Draggable.createGlobalKind<CardPayload>('myapp/card');

Keys are shared by the whole page, so a bare name like 'card' could collide with a kind from another library. Prefix keys with your app or package name. Both sides must also agree on the payload type: TypeScript can’t check that across bundles, so a mismatch surfaces at runtime.

Prefer createKind whenever the source and the target can import the same constant.

Parameters

key^*string—

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

Return value

DragKind<TPayload, TDragData>

anyKind constant

A kind that matches every drag. Pass it to a target’s accept prop to accept everything. The resulting source.payload is unknown until narrowed with a specific kind’s matches method.

Accepting every drag

<Draggable.Target
  accept={Draggable.anyKind}
  onDraggableDrop={({ source }) => {
    if (card.matches(source)) {
      archive(source.payload);
    }
  }}
/>

Modifiers

The built-in movement modifiers. Pass them to the modifiers prop of <Draggable.Root> or <Draggable.Preview>.

restrictToVerticalAxis

Locks the drag to the vertical axis.

Parameters

context^*DragModifierContext—

Name: context
Type: DragModifierContext

Return value

DragPosition

restrictToHorizontalAxis

Locks the drag to the horizontal axis.

Parameters

context^*DragModifierContext—

Name: context
Type: DragModifierContext

Return value

DragPosition

restrictToParentElement

Keeps the drag inside the source element’s parent.

Parameters

context^*DragModifierContext—

Name: context
Type: DragModifierContext

Return value

DragPosition

restrictToElement

Keeps the drag inside an element. Accepts the element, a ref to it, or a function returning it. The element is measured on every move, so it can scroll or resize during the drag.

Parameters

element^*DragElementReference—

Name: element
Type: DragElementReference

Return value

DragModifier

restrictToWindowEdges

Keeps the drag inside the browser viewport.

Parameters

context^*DragModifierContext—

Name: context
Type: DragModifierContext

Return value

DragPosition

snapToGrid

Snaps the drag to a grid anchored where the drag started. Pass a number for a square grid, or { x, y } for a rectangular one. A step of 0 leaves that axis free.

The step is in the source’s own units, so snapToGrid(20) still snaps to a 20-unit grid on a zoomed canvas.

Parameters

size^*Union—

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

Return value

DragModifier

DragModifier

The type of a custom modifier.

Parameters

context^*DragModifierContext—

Name: context
Type: DragModifierContext

Return value

DragPosition

useActiveDrag

Returns the source of the drag in progress, or null when nothing is being dragged. The component re-renders when a drag starts or ends. It works anywhere on the page, with or without a <Draggable.Provider>.

Pass a kind, or an array of kinds, to observe only those drags and type source.payload. Other drags return null.

Reading the active drag

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

Parameters

accept^*AnyDragAccept—

Name: accept
Type: AnyDragAccept | undefined

Return value

UseActiveDragReturnValue<TPayload | unknown, TDragData | unknown>

Draggable.useActiveDrag.ReturnValueHide

type DraggableuseActiveDragReturnValue<TPayload = unknown, TDragData = unknown> = DragSource<
  TPayload,
  TDragData
> | null

useDragMonitor

Observes drags anywhere on the page without an element or a <Draggable.Provider>. Use it for status indicators, analytics, or handling drops in one place.

Pass accept to filter by kind and infer the type of source.payload. Omit it to observe every drag with an unknown payload.

Reacting to every stage of a drag

Draggable.useDragMonitor({
  accept: card,
  // Fires once when a matching drag starts.
  onMoveStart: ({ source }) => console.log('picked up', source.payload.title),
  // Fires as the pointer moves, at most once per animation frame.
  onMove: ({ location }) => console.log('at', location.current.input.clientX),
  // Fires when the drop targets under the pointer change.
  onTargetChange: ({ location }) =>
    console.log('over', location.current.dropTargets[0]?.payload ?? 'nothing'),
  // Fires once when the drag ends.
  onMoveEnd: ({ source, dropTarget }, eventDetails) => {
    if (eventDetails.reason === 'drop' && dropTarget !== null) {
      console.log('dropped', source.payload.title, 'on', dropTarget.payload);
    }
  },
});

Monitors support the same handlers as <Draggable.Root>, except onBeforeMoveStart. A monitor mounted during a drag observes the remaining events, so onMoveEnd can fire without a preceding onMoveStart.

Parameters

parameters^*

DragParametersWithInferredAccept<
  UseDragMonitorParameters<
    TPayload | unknown,
    TDragData | unknown
  >,
  AnyDragAccept
>

—

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

Return value

void

Draggable.useDragMonitor.ParametersHide

type DraggableuseDragMonitorParameters<TSourcePayload = unknown, TDragData = unknown> = {
  accept?: DragAccept<TSourcePayload, TDragData>;
  /**
   * Event handler called once when a matching drag starts, wherever it started.
   * A monitor registered during a drag doesn't receive it for that drag.
   */
  onMoveStart?: (
    parameters: MoveStartEvent<TSourcePayload, TDragData>,
    eventDetails: MoveStartEventDetails,
  ) => void;
  /**
   * Event handler called as the pointer moves or a modifier key changes,
   * at most once per animation frame.
   */
  onMove?: (
    parameters: MoveEvent<TSourcePayload, TDragData>,
    eventDetails: MoveEventDetails,
  ) => void;
  /** Event handler called when the drop targets under the pointer change. */
  onTargetChange?: (
    parameters: DropTargetChangeEvent<TSourcePayload, TDragData>,
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called once when the drag ends, after a drop, a release outside any
   * target, or a cancellation. `eventDetails.reason` identifies the outcome, and
   * `dropTarget` is the target of a drop, or `null`.
   *
   * It can fire without a preceding `onMoveStart`, for example when the monitor
   * registered during the drag, so don't assume the two are paired.
   */
  onMoveEnd?: (
    parameters: MoveEndEvent<TSourcePayload, TDragData>,
    eventDetails: MoveEndEventDetails,
  ) => void;
}

Draggable.useDragMonitor.ReturnValueHide

type DraggableuseDragMonitorReturnValue = Draggable.useDragMonitor.ReturnValue

useDragDropManager

Returns the page-wide drag manager. Use it to register existing DOM elements as drag sources, drop targets, or scroll containers. The hook requires a <Draggable.Provider> above the calling component.

All calls share the same manager, and cancelDrag() ends the active drag. Use distinct kinds to keep unrelated features separate.

Getting the manager

const manager = Draggable.useDragDropManager();

Source, target, and scroll registrations take an element and a function returning its options. Monitor registration takes only the options function. Each method returns a cleanup function. Register in an effect and return the cleanup:

Registering from an effect

React.useEffect(() => {
  return manager.registerDraggable(element, () => ({ kind: card, payload: id }));
}, [manager, id]);

The manager and its registration methods are stable and can be listed as effect dependencies. Base UI reads each option at the following times:

Option	When it’s read
Event handlers and predicates, such as `canDrop`	Every time they’re needed, so they see the latest closure.
A source’s `kind` and preview settings	Once when a drag starts.
A source’s `payload`	At pickup, and whenever it changes during the drag.
A target’s `kind` and `payload`	Each time the target is evaluated, including on drop.
`disabled`, `dragHandle`, and the styles applied while idle	At registration and on the next `pointerdown`. Re-register to apply a change at once.

registerDraggable

Registers a drag source. It accepts the options of <Draggable.Root>, plus dragHandle to restrict pickup to an element, and dragPreview to configure the preview:

Registering a source

manager.registerDraggable(element, () => ({
  kind: card,
  payload: id,
  dragHandle: handleRef,
  dragPreview: { offset: 'pointer' },
}));

dragPreview takes the options of <Draggable.Preview>. Pass a render function instead of children to show custom content:

A custom preview for a registered source

manager.registerDraggable(element, () => ({
  kind: card,
  payload: id,
  dragPreview: {
    render: ({ source }) => <span className="Chip">{source.payload}</span>,
    offset: 'pointer',
  },
}));

registerDropTarget

Registers a drop target. It accepts the options of <Draggable.Target>, except trackDragOver, since there is no React state to update. accept is required here.

Registering a target

manager.registerDropTarget(element, () => ({
  accept: card,
  onDraggableDrop: ({ source }) => moveCard(source.payload),
}));

TypeScript infers source.payload from accept but can’t infer the target’s own payload through the options function. Pass both type arguments, as in registerDropTarget<typeof card, SlotPayload>, when the target reads target.payload.

registerAutoScroller

Registers a scroll container, with the options of <Draggable.Viewport>. Use it to scroll the page, or for a container rendered by code you don’t control:

A container that appears later

React.useEffect(() => {
  const scrollElement = gridApi.getScrollElement();
  if (!scrollElement) {
    return undefined;
  }
  return manager.registerAutoScroller(scrollElement, () => ({
    maxSpeed: 600,
    overflowMargin: { top: 80, bottom: 80 },
  }));
}, [manager, gridApi]);

registerMonitor

Registers a monitor with the options of useDragMonitor:

Registering a monitor

manager.registerMonitor(() => ({
  accept: card,
  onMoveStart: ({ source }) => setActiveId(source.payload),
  onMoveEnd: () => setActiveId(null),
}));

cancelDrag

Ends the drag in progress. onMoveEnd fires with canceled: true and the 'imperative-action' reason. It does nothing when no drag is active. Use it when a route change, a dialog, or a deleted record invalidates the drag:

Canceling on navigation

const manager = Draggable.useDragDropManager();

React.useEffect(() => {
  return router.subscribe(() => manager.cancelDrag());
}, [manager]);

Return value

UseDragDropManagerReturnValue

registerDraggablefunction

Name: registerDraggable
Description: Registers an element as a drag source, with the options of Draggable.Root. Returns a cleanup function that unregisters it.
Type: | (<TPayload, TDragData = unknown>( element: HTMLElement, getParameters: () => RegisterDraggableParametersWithPayload< TPayload, TDragData >, ) => () => void) | (< TKind extends DragKind<undefined, any> = DragKind< undefined, unknown >, >( element: HTMLElement, getParameters: () => { payload?: undefined; previewKey?: string | number; dragHandle?: DragHandle; disabled?: boolean; onBeforeMoveStart?: ( context: MoveStartContext< undefined, TDragData | unknown >, eventDetails: BeforeMoveStartEventDetails, ) => void; activation?: DragActivationConfig | DragActivationConfig[]; modifiers?: DragModifiers; dragCursor?: string | false; dragPreview?: DragPreviewParameters< undefined, TDragData | unknown >; onMoveStart?: ( parameters: MoveStartEvent< undefined, TDragData | unknown >, eventDetails: MoveStartEventDetails, ) => void; onMove?: ( parameters: MoveEvent< undefined, TDragData | unknown >, eventDetails: MoveEventDetails, ) => void; onTargetChange?: ( parameters: DropTargetChangeEvent< undefined, TDragData | unknown >, eventDetails: DropTargetChangeEventDetails, ) => void; onMoveEnd?: ( parameters: MoveEndEvent< undefined, TDragData | unknown >, eventDetails: MoveEndEventDetails, ) => void; kind: TKind; }, ) => () => void)

registerDropTargetfunction

Name: registerDropTarget
Description: Registers an element as a drop target, with the options of Draggable.Target. Returns a cleanup function that unregisters it.
Type: < TAccept extends AnyDragAccept = DragKind, TTargetPayload = undefined, TKind extends DragKind<TTargetPayload, any> | undefined = DragKind<TTargetPayload, unknown> | undefined, >( element: HTMLElement, getParameters: () => Omit< RegisterDropTargetParameters< TPayload | unknown, TTargetPayload, TDragData | unknown, TDragData | unknown >, 'kind' > & { accept: TAccept; } & DragParametersWithTargetKind<TKind> & ({} | { payload: TTargetPayload }), ) => () => void

registerAutoScrollerfunction

Name: registerAutoScroller
Description: Registers a scroll container, with the options of Draggable.Viewport. Pass document.documentElement to scroll the page. Returns a cleanup function that unregisters it.
Type: <TAccept extends AnyDragAccept = DragKind>( element: HTMLElement, getParameters: () => DragParametersWithInferredAccept< RegisterAutoScrollerParameters< TPayload | unknown, TDragData | unknown >, TAccept >, ) => () => void

registerMonitorfunction

Name: registerMonitor
Description: Registers a monitor, with the options of useDragMonitor. Returns a cleanup function that unregisters it.
Type: <TAccept extends AnyDragAccept = DragKind>( getParameters: () => DragParametersWithInferredAccept< RegisterMonitorParameters< TPayload | unknown, TDragData | unknown >, TAccept >, ) => () => void

cancelDragfunction

Name: cancelDrag
Description: Cancels the drag in progress, if any. onMoveEnd fires with canceled: true and the 'imperative-action' reason.
Type: () => void

Draggable.useDragDropManager.ReturnValueHide

type DraggableuseDragDropManagerReturnValue = {
  /**
   * Registers an element as a drag source, with the options of `Draggable.Root`.
   * Returns a cleanup function that unregisters it.
   */
  registerDraggable:
    | (<TPayload, TDragData = unknown>(
        element: HTMLElement,
        getParameters: () => RegisterDraggableParametersWithPayload<TPayload, TDragData>,
      ) => (() => void))
    | (<TKind extends DragKind<undefined, any> = DragKind<undefined, unknown>>(
        element: HTMLElement,
        getParameters: () => {
          payload?: undefined;
          previewKey?: string | number;
          dragHandle?: DragHandle;
          disabled?: boolean;
          onBeforeMoveStart?: (
            context: MoveStartContext<undefined, TDragData | unknown>,
            eventDetails: BeforeMoveStartEventDetails,
          ) => void;
          activation?: DragActivationConfig | DragActivationConfig[];
          modifiers?: DragModifiers;
          dragCursor?: string | false;
          dragPreview?: DragPreviewParameters<undefined, TDragData | unknown>;
          onMoveStart?: (
            parameters: MoveStartEvent<undefined, TDragData | unknown>,
            eventDetails: MoveStartEventDetails,
          ) => void;
          onMove?: (
            parameters: MoveEvent<undefined, TDragData | unknown>,
            eventDetails: MoveEventDetails,
          ) => void;
          onTargetChange?: (
            parameters: DropTargetChangeEvent<undefined, TDragData | unknown>,
            eventDetails: DropTargetChangeEventDetails,
          ) => void;
          onMoveEnd?: (
            parameters: MoveEndEvent<undefined, TDragData | unknown>,
            eventDetails: MoveEndEventDetails,
          ) => void;
          kind: TKind;
        },
      ) => (() => void));
  /**
   * Registers an element as a drop target, with the options of `Draggable.Target`.
   * Returns a cleanup function that unregisters it.
   */
  registerDropTarget: <
    TAccept extends AnyDragAccept = DragKind,
    TTargetPayload = undefined,
    TKind extends DragKind<TTargetPayload, any> | undefined =
      DragKind<TTargetPayload, unknown> | undefined,
  >(
    element: HTMLElement,
    getParameters: () => Omit<
      RegisterDropTargetParameters<
        TPayload | unknown,
        TTargetPayload,
        TDragData | unknown,
        TDragData | unknown
      >,
      'kind'
    > & { accept: TAccept } & DragParametersWithTargetKind<TKind> &
      ({} | { payload: TTargetPayload }),
  ) => (() => void);
  /**
   * Registers a scroll container, with the options of `Draggable.Viewport`.
   * Pass `document.documentElement` to scroll the page.
   * Returns a cleanup function that unregisters it.
   */
  registerAutoScroller: <TAccept extends AnyDragAccept = DragKind>(
    element: HTMLElement,
    getParameters: () => DragParametersWithInferredAccept<
      RegisterAutoScrollerParameters<TPayload | unknown, TDragData | unknown>,
      TAccept
    >,
  ) => (() => void);
  /**
   * Registers a monitor, with the options of `useDragMonitor`.
   * Returns a cleanup function that unregisters it.
   */
  registerMonitor: <TAccept extends AnyDragAccept = DragKind>(
    getParameters: () => DragParametersWithInferredAccept<
      RegisterMonitorParameters<TPayload | unknown, TDragData | unknown>,
      TAccept
    >,
  ) => (() => void);
  /**
   * Cancels the drag in progress, if any. `onMoveEnd` fires with `canceled: true`
   * and the `'imperative-action'` reason.
   */
  cancelDrag: () => void;
}

AutoScrollOverflowMarginHide

type AutoScrollOverflowMargin =
  number | { top?: number; right?: number; bottom?: number; left?: number }

DragActivationHide

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

DragActivationConfigHide

type DragActivationConfig =
  DragActivation | { mouse?: DragActivation; touch?: DragActivation; pen?: DragActivation }

DragAutoScrollDirectionHide

type DragAutoScrollDirection = 'horizontal' | 'vertical'

DragAutoScrollEventHide

type DragAutoScrollEvent<TSourcePayload = unknown, TDragData = unknown> = {
  /**
   * How far to move horizontally this frame, in CSS pixels, with `scrollBy`
   * semantics: a positive value moves the view right, so the content slides left
   * under the pointer. Apply this delta as-is, without multiplying by elapsed time.
   * `0` when the horizontal axis isn't engaged this frame.
   */
  x: number;
  /** How far to move vertically this frame, in CSS pixels. A positive value moves the view down. */
  y: number;
  direction: DragAutoScrollDirection;
  /**
   * The position used to determine scrolling. It may differ from the modified
   * drag position when a modifier separates that position from the pointer.
   */
  input: DragInput;
  source: DragSource<TSourcePayload, TDragData>;
  element: HTMLElement;
}

DragAutoScrollEventDetailsHide

type DragAutoScrollEventDetails = {
  /** Why the frame ran. Always `'pointer'`: the loop follows the pointer's position. */
  reason: 'pointer';
  /** A generic `Event`, rather than the native pointer event. */
  event: Event;
  /** Prevents Base UI from scrolling the container in this direction. */
  cancel: () => void;
  /** Whether `cancel` has been called. */
  isCanceled: boolean;
  /**
   * Claims this direction, so that ancestor viewports don't scroll on the same axis.
   * Skip it at a bound the element can't move past, so an ancestor can scroll instead.
   */
  consume: () => void;
  /** Whether `consume` has been called. */
  isConsumed: boolean;
}

DragAutoScrollFrameContextHide

type DragAutoScrollFrameContext<TSourcePayload = unknown, TDragData = unknown> = {
  /**
   * The position used to determine scrolling. It may differ from the modified
   * drag position when a modifier separates that position from the pointer.
   */
  input: DragInput;
  source: DragSource<TSourcePayload, TDragData>;
  element: HTMLElement;
}

DragDropManagerHide

type DragDropManager = {
  /**
   * Registers an element as a drag source, with the options of `Draggable.Root`.
   * Returns a cleanup function that unregisters it.
   */
  registerDraggable:
    | (<TPayload, TDragData = unknown>(
        element: HTMLElement,
        getParameters: () => RegisterDraggableParametersWithPayload<TPayload, TDragData>,
      ) => (() => void))
    | (<TKind extends DragKind<undefined, any> = DragKind<undefined, unknown>>(
        element: HTMLElement,
        getParameters: () => {
          payload?: undefined;
          previewKey?: string | number;
          dragHandle?: DragHandle;
          disabled?: boolean;
          onBeforeMoveStart?: (
            context: MoveStartContext<undefined, TDragData | unknown>,
            eventDetails: BeforeMoveStartEventDetails,
          ) => void;
          activation?: DragActivationConfig | DragActivationConfig[];
          modifiers?: DragModifiers;
          dragCursor?: string | false;
          dragPreview?: DragPreviewParameters<undefined, TDragData | unknown>;
          onMoveStart?: (
            parameters: MoveStartEvent<undefined, TDragData | unknown>,
            eventDetails: MoveStartEventDetails,
          ) => void;
          onMove?: (
            parameters: MoveEvent<undefined, TDragData | unknown>,
            eventDetails: MoveEventDetails,
          ) => void;
          onTargetChange?: (
            parameters: DropTargetChangeEvent<undefined, TDragData | unknown>,
            eventDetails: DropTargetChangeEventDetails,
          ) => void;
          onMoveEnd?: (
            parameters: MoveEndEvent<undefined, TDragData | unknown>,
            eventDetails: MoveEndEventDetails,
          ) => void;
          kind: TKind;
        },
      ) => (() => void));
  /**
   * Registers an element as a drop target, with the options of `Draggable.Target`.
   * Returns a cleanup function that unregisters it.
   */
  registerDropTarget: <
    TAccept extends AnyDragAccept = DragKind,
    TTargetPayload = undefined,
    TKind extends DragKind<TTargetPayload, any> | undefined =
      DragKind<TTargetPayload, unknown> | undefined,
  >(
    element: HTMLElement,
    getParameters: () => Omit<
      RegisterDropTargetParameters<
        TPayload | unknown,
        TTargetPayload,
        TDragData | unknown,
        TDragData | unknown
      >,
      'kind'
    > & { accept: TAccept } & DragParametersWithTargetKind<TKind> &
      ({} | { payload: TTargetPayload }),
  ) => (() => void);
  /**
   * Registers a scroll container, with the options of `Draggable.Viewport`.
   * Pass `document.documentElement` to scroll the page.
   * Returns a cleanup function that unregisters it.
   */
  registerAutoScroller: <TAccept extends AnyDragAccept = DragKind>(
    element: HTMLElement,
    getParameters: () => DragParametersWithInferredAccept<
      RegisterAutoScrollerParameters<TPayload | unknown, TDragData | unknown>,
      TAccept
    >,
  ) => (() => void);
  /**
   * Registers a monitor, with the options of `useDragMonitor`.
   * Returns a cleanup function that unregisters it.
   */
  registerMonitor: <TAccept extends AnyDragAccept = DragKind>(
    getParameters: () => DragParametersWithInferredAccept<
      RegisterMonitorParameters<TPayload | unknown, TDragData | unknown>,
      TAccept
    >,
  ) => (() => void);
  /**
   * Cancels the drag in progress, if any. `onMoveEnd` fires with `canceled: true`
   * and the `'imperative-action'` reason.
   */
  cancelDrag: () => void;
}

Draggable.AcceptedDragDataHide

type DraggableAcceptedDragData = TDragData | unknown

Draggable.AcceptedDragPayloadHide

type DraggableAcceptedDragPayload = TPayload | unknown

Draggable.AnyDragAcceptHide

type DraggableAnyDragAccept = DragAcceptedKind | DragAcceptedKind[]

Draggable.anyKindHide

type DraggableanyKind = {
  /** The name or global key the kind was created with. A debugging aid only. */
  name: string;
  /**
   * The kind's identity. Unique per `createKind` call, and shared by `createGlobalKind`
   * calls with the same key.
   */
  id: symbol;
  /** Whether a drag source is of this kind. Narrows its `payload` type. */
  matches: (type matches =
  | ((source: {
      element: HTMLElement;
      kind: symbol;
      dragHandle: Element | null;
      payload: unknown;
      updatePayload: unknown;
      dragData: unknown;
      updateDragData: unknown;
    }) => boolean)
  | ((target: {
      element: Element;
      kind: symbol | undefined;
      payload: unknown;
      updatePayload: unknown;
      dragData: unknown;
      updateDragData: unknown;
      getLocalPoint: unknown;
      getSnappedLocalPoint: unknown;
    }) => boolean));
}

Draggable.BaseDragEventHide

type DraggableBaseDragEvent<TSourcePayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
}

Draggable.BeforeMoveStartEventDetailsHide

type DraggableBeforeMoveStartEventDetails = (
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }
) & {
  /** 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;
}

Draggable.DragAcceptHide

type DraggableDragAccept<TPayload, TDragData = unknown> =
  DragAcceptedKind<TPayload, TDragData> | DragAcceptedKind<TPayload, TDragData>[]

Draggable.DragAcceptedKindHide

type DraggableDragAcceptedKind = {
  /**
   * The kind's identity. Unique per `createKind` call, and shared by `createGlobalKind`
   * calls with the same key.
   */
  id: symbol;
  /** The name or global key the kind was created with. A debugging aid only. */
  name: string;
  /** Whether a drag source is of this kind. Narrows its `payload` type. */
  matches: (type matches =
  | ((source: {
      element: HTMLElement;
      kind: symbol;
      dragHandle: Element | null;
      payload: unknown;
      updatePayload: unknown;
      dragData: unknown;
      updateDragData: unknown;
    }) => boolean)
  | ((target: {
      element: Element;
      kind: symbol | undefined;
      payload: unknown;
      updatePayload: unknown;
      dragData: unknown;
      updateDragData: unknown;
      getLocalPoint: unknown;
      getSnappedLocalPoint: unknown;
    }) => boolean));
}

Draggable.DragCanceledReasonHide

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

Draggable.DragCompletedReasonHide

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

Draggable.DragDropEventHide

type DraggableDragDropEvent<TSourcePayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  dropTarget: DropTargetRecord;
}

Draggable.DragDropEventDetailsHide

type DraggableDragDropEventDetails = {
  /** Why the event fired. */
  reason: 'drop';
  /**
   * The native event. Reasons that don't come from a native event, such as
   * `'imperative-action'`, carry a generic `Event`.
   */
  event: PointerEvent | MouseEvent;
}

Draggable.DragDropReasonHide

type DraggableDragDropReason = 'drop'

Draggable.DragElementReferenceHide

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

Draggable.DragEndReasonHide

type DraggableDragEndReason = DragCompletedReason | DragCanceledReason

Draggable.DragEventDetailsHide

type DraggableDragEventDetails<TReason extends string> = {
  /** Why the event fired. */
  reason: TReason;
  /**
   * The native event. Reasons that don't come from a native event, such as
   * `'imperative-action'`, carry a generic `Event`.
   */
  event: PointerEvent | MouseEvent | KeyboardEvent | FocusEvent | Event;
}

Draggable.DraggableEventDetailsMapHide

type DraggableDraggableEventDetailsMap = {
  onMoveStart: MoveStartEventDetails;
  onMove: MoveEventDetails;
  onTargetChange: DropTargetChangeEventDetails;
  onMoveEnd: MoveEndEventDetails;
}

Draggable.DraggableEventMapHide

type DraggableDraggableEventMap<TSourcePayload = unknown, TDragData = unknown> = {
  onMoveStart: MoveStartEvent<TSourcePayload, TDragData>;
  onMove: MoveEvent<TSourcePayload, TDragData>;
  onTargetChange: DropTargetChangeEvent<TSourcePayload, TDragData>;
  onMoveEnd: MoveEndEvent<TSourcePayload, TDragData>;
}

Draggable.DraggablePayloadHide

type DraggableDraggablePayload = TPayload

Draggable.DragHandleHide

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

Draggable.DragInputHide

type DraggableDragInput = {
  /**
   * `MouseEvent.button` semantics: 0 = primary, 1 = middle, 2 = secondary.
   * Move-derived events (`onMove`, `onTargetChange`) 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. */
  pointerType: DragPointerType;
  /** 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;
}

Draggable.DragKindHide

type DraggableDragKind<TPayload = unknown, TDragData = unknown> = {
  /** The name or global key the kind was created with. A debugging aid only. */
  name: string;
  /**
   * The kind's identity. Unique per `createKind` call, and shared by `createGlobalKind`
   * calls with the same key.
   */
  id: symbol;
  /** Whether a drag source is of this kind. Narrows its `payload` type. */
  matches: (type matches =
  | ((source: {
      element: HTMLElement;
      kind: symbol;
      dragHandle: Element | null;
      payload: unknown;
      updatePayload: unknown;
      dragData: unknown;
      updateDragData: unknown;
    }) => boolean)
  | ((target: {
      element: Element;
      kind: symbol | undefined;
      payload: unknown;
      updatePayload: unknown;
      dragData: unknown;
      updateDragData: unknown;
      getLocalPoint: unknown;
      getSnappedLocalPoint: unknown;
    }) => boolean));
}

Draggable.DragLocalPointHide

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

Draggable.DragLocationHide

type DraggableDragLocation = {
  /** The pointer state. */
  input: DragInput;
  /** The drop targets under the pointer, innermost first. */
  dropTargets: DropTargetRecord[];
}

Draggable.DragLocationHistoryHide

type DraggableDragLocationHistory = {
  /** The pointer's offset from the source's top-left corner at pickup, in CSS pixels. */
  grabOffset?: DragPosition;
  /** The location where the drag started. */
  initial: DragLocation;
  /** The location at the moment this event fires. */
  current: DragLocation;
  /**
   * The location at the previous event. On the first event of a drag, it holds the
   * pickup position and no drop targets.
   */
  previous: DragLocation;
}

Draggable.DragModifierContextHide

type DraggableDragModifierContext = {
  /**
   * The point to constrain, in client pixels. On `Draggable.Root`, it's the pointer
   * position. On `Draggable.Preview`, it's the preview's proposed top-left corner.
   */
  point: DragPosition;
  /** The same point when the drag started. Axis locks and grid snaps anchor to it. */
  initialPoint: DragPosition;
  /**
   * The point before any modifier of this chain ran, in client pixels.
   * On `Draggable.Preview`, it already includes the root's modifiers.
   */
  input: DragPosition;
  /** The drag source element. */
  sourceElement: HTMLElement;
  /** The source element's bounding rectangle when the drag started. */
  sourceRect: DOMRect;
  /**
   * The scale applied to the element by CSS `transform` or `zoom`, including its
   * ancestors. `1` when nothing is scaled. Multiply a distance in the element's own
   * units by this value to convert it to client pixels.
   */
  scale: DragPosition;
  /** The preview element's current bounding rectangle, or `null` when there is no preview. */
  previewRect: DOMRect | null;
  /**
   * The offset from the preview's top-left corner to `point`. `{ x: 0, y: 0 }` on
   * `Draggable.Preview` and when there is no preview.
   */
  previewOffset: DragPosition;
  /**
   * Whether the Control key is held. Pressing or releasing a modifier key
   * reapplies the modifiers on the next frame.
   */
  ctrlKey: boolean;
  /** Whether the Shift key is held. */
  shiftKey: boolean;
  /** Whether the Alt key is held. */
  altKey: boolean;
  /** Whether the Meta (Command or Windows) key is held. */
  metaKey: boolean;
  /** The window of the source's document. */
  ownerWindow: Window;
}

Draggable.DragModifiersHide

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

Draggable.DragMoveReasonHide

type DraggableDragMoveReason = 'pointer' | 'modifier-key'

Draggable.DragPointerTypeHide

type DraggableDragPointerType = 'mouse' | 'pen' | 'touch'

Draggable.DragPositionHide

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

Draggable.DragPreviewContainerHide

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

Draggable.DragPreviewOffsetHide

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

Draggable.DragPreviewOffsetParametersHide

type DraggableDragPreviewOffsetParameters = {
  /** 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;
}

Draggable.DragPreviewParametersHide

type DraggableDragPreviewParameters<TSourcePayload = unknown, TDragData = unknown> = {
  /**
   * Renders the preview content instead of cloning the source.
   * Return `null` to show no preview for this drag.
   */
  render?: (parameters: DragPreviewRenderEvent<TSourcePayload, TDragData>) => React.ReactNode;
  /**
   * Where the preview sits relative to the pointer.
   * @default 'source'
   */
  offset?: DragPreviewOffset;
  /**
   * One or more modifiers that constrain the preview only. The drop position still
   * follows the pointer. To constrain the drag itself, use `modifiers` on `Draggable.Root`.
   */
  modifiers?: DragModifiers;
  /**
   * Whether to show no preview. The drag still runs.
   * @default false
   */
  disabled?: boolean;
  /**
   * Where to insert the preview element in the DOM. Defaults to beside the source,
   * so the same CSS applies to it. Pass a container to keep selectors such as
   * `:last-child` on the source's siblings unchanged during the drag.
   */
  container?: DragPreviewContainer;
}

Draggable.DragPreviewRenderEventHide

type DraggableDragPreviewRenderEvent<TSourcePayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
}

Draggable.DragPreviewSettingsHide

type DraggableDragPreviewSettings = {
  /**
   * Where the preview sits relative to the pointer.
   * @default 'source'
   */
  offset?: DragPreviewOffset;
  /**
   * One or more modifiers that constrain the preview only. The drop position still
   * follows the pointer. To constrain the drag itself, use `modifiers` on `Draggable.Root`.
   */
  modifiers?: DragModifiers;
  /**
   * Whether to show no preview. The drag still runs.
   * @default false
   */
  disabled?: boolean;
  /**
   * Where to insert the preview element in the DOM. Defaults to beside the source,
   * so the same CSS applies to it. Pass a container to keep selectors such as
   * `:last-child` on the source's siblings unchanged during the drag.
   */
  container?: DragPreviewContainer;
}

Draggable.DragSnappedLocalPointOptionsHide

type DraggableDragSnappedLocalPointOptions = {
  /**
   * The point to snap: the pointer position, or the dragged element's top-left corner.
   * Use `'source'` when committing where the element lands.
   * @default 'pointer'
   */
  anchor?: 'pointer' | 'source';
}

Draggable.DragSnapStepsHide

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

Draggable.DragSourceHide

type DraggableDragSource<TPayload = unknown, TDragData = unknown> = {
  /** The draggable's own DOM element. */
  element: HTMLElement;
  /**
   * The identity of the draggable's `kind`.
   * Test it with a kind's `matches` method, which also narrows `payload`.
   */
  kind: symbol;
  /** The handle the user pressed, or `null` when the whole draggable is its own handle. */
  dragHandle: Element | null;
  /** The draggable's `payload`, or `undefined` when it has none. */
  payload: TPayload;
  /** Replaces the payload. The new value persists after the drag, until the `payload` prop changes. */
  updatePayload: ((payload: unknown) => void);
  /** Data stored for the current drag. Starts as `undefined` on every drag. */
  dragData: TDragData | undefined;
  /** Stores data for the rest of the current drag. */
  updateDragData: ((dragData: unknown) => void);
}

Draggable.DragStartReasonHide

type DraggableDragStartReason = 'pointer' | 'double-click'

Draggable.DropEventHide

type DraggableDropEvent<
  TSourcePayload = unknown,
  TTargetPayload = unknown,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The drop target's own record. */
  target: DropTargetRecord<TTargetPayload, TTargetDragData>;
  dropTarget: DropTargetRecord<TTargetPayload, TTargetDragData>;
}

Draggable.DropTargetChangeEventHide

type DraggableDropTargetChangeEvent<TSourcePayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
}

Draggable.DropTargetChangeEventDetailsHide

type DraggableDropTargetChangeEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }
  | { reason: 'modifier-key'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | MouseEvent }
  | { reason: 'outside-release'; event: PointerEvent | MouseEvent }
  | { 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 }

Draggable.DropTargetChangeReasonHide

type DraggableDropTargetChangeReason =
  | 'pointer'
  | 'double-click'
  | 'modifier-key'
  | 'escape-key'
  | 'tab-key'
  | 'drop'
  | 'outside-release'
  | 'imperative-action'
  | 'window-blur'
  | 'page-hidden'
  | 'pointer-canceled'
  | 'capture-lost'
  | 'missed-release'
  | 'document-detached'
  | 'handler-error'

Draggable.DropTargetEventHide

type DraggableDropTargetEvent<
  K extends
    | 'onDraggableDrop'
    | 'onDraggableStart'
    | 'onDraggableMove'
    | 'onDraggableEnter'
    | 'onDraggableLeave',
  TSourcePayload = unknown,
  TTargetPayload = unknown,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The drop target's own record. */
  target: DropTargetRecord<TTargetPayload, TTargetDragData>;
}

Draggable.DropTargetEventDetailsMapHide

type DraggableDropTargetEventDetailsMap = {
  onDraggableStart: MoveStartEventDetails;
  onDraggableMove: MoveEventDetails;
  onDraggableEnter: DropTargetChangeEventDetails;
  onDraggableLeave: DropTargetChangeEventDetails;
  onDraggableDrop: DragDropEventDetails;
}

Draggable.DropTargetEventMapHide

type DraggableDropTargetEventMap<TSourcePayload = unknown, TDragData = unknown> = {
  onDraggableStart: MoveStartEvent<TSourcePayload, TDragData>;
  onDraggableMove: MoveEvent<TSourcePayload, TDragData>;
  onDraggableEnter: BaseDragEvent<TSourcePayload, TDragData>;
  onDraggableLeave: BaseDragEvent<TSourcePayload, TDragData>;
  onDraggableDrop: DragDropEvent<TSourcePayload, TDragData>;
}

Draggable.DropTargetEventTargetHide

type DraggableDropTargetEventTarget<TTargetPayload = unknown, TTargetDragData = unknown> = {
  /** The drop target's own record. */
  target: DropTargetRecord<TTargetPayload, TTargetDragData>;
}

Draggable.DropTargetPayloadHide

type DraggableDropTargetPayload = TTargetPayload

Draggable.DropTargetRecordHide

type DraggableDropTargetRecord<TTargetPayload = unknown, TDragData = unknown> = {
  /** The drop target's own DOM element. */
  element: Element;
  /**
   * The identity of the target's `kind`, or `undefined` when it has none.
   * Test it with a kind's `matches` method, which also narrows `payload`.
   */
  kind: symbol | undefined;
  /** The target's `payload`, or `undefined` when it has none. */
  payload: TTargetPayload;
  /** Replaces the payload until the `payload` prop changes. */
  updatePayload: ((payload: unknown) => void);
  /** Data stored for this target during the current drag. Starts as `undefined`. */
  dragData: TDragData | undefined;
  /** Stores data for this target for the rest of the current drag. */
  updateDragData: ((dragData: unknown) => void);
  /**
   * Returns where the pointer is within this target, as a fraction of its size on
   * each axis: `0` at the left or top edge, `1` at the right or bottom edge.
   * Use it when a drop means a value spread across the target, such as a time in a day column:
   *
   * ```tsx
   * <Draggable.Target
   *   accept={eventKind}
   *   onDraggableDrop={({ target }) => {
   *     schedule(target.getLocalPoint().y * MINUTES_PER_DAY);
   *   }}
   * />
   * ```
   *
   * The value isn't clamped, since an outer target can have the pointer outside its
   * own box while a nested target is under it. A target with no size reports `0` on both axes.
   */
  getLocalPoint: () => DragLocalPoint;
  /**
   * Returns `getLocalPoint()` rounded to the target's `snap` steps and clamped between `0` and `1`:
   *
   * ```tsx
   * <Draggable.Target
   *   accept={eventKind}
   *   snap={{ y: 96 }}
   *   onDraggableDrop={({ source, target }) => {
   *     // Already a multiple of 15 minutes.
   *     schedule(source.payload.id, target.getSnappedLocalPoint().y * MINUTES_PER_DAY);
   *   }}
   * />
   * ```
   *
   * Pass `{ anchor: 'source' }` to snap the dragged element's top-left corner instead
   * of the pointer. An axis without steps returns its clamped fraction.
   */
  getSnappedLocalPoint: (options?: DragSnappedLocalPointOptions) => DragLocalPoint;
}

Draggable.DropTargetResolutionContextHide

type DraggableDropTargetResolutionContext<TSourcePayload = unknown, TDragData = unknown> = {
  /** The current pointer state. */
  input: DragInput;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /** The drop target's own DOM element. */
  element: Element;
}

Draggable.MoveEndEventHide

type DraggableMoveEndEvent<TSourcePayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
  /**
   * Whether the drag was canceled rather than released. A release outside any drop
   * target isn't a cancellation. Read `eventDetails.reason` for the exact outcome.
   */
  canceled: boolean;
  /**
   * The drop target that received the drop, or `null` when the drag was released
   * outside any target or canceled.
   */
  dropTarget: DropTargetRecord | null;
}

Draggable.MoveEndEventDetailsHide

type DraggableMoveEndEventDetails =
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'tab-key'; event: KeyboardEvent }
  | { reason: 'drop'; event: PointerEvent | MouseEvent }
  | { reason: 'outside-release'; event: PointerEvent | MouseEvent }
  | { 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 }

Draggable.MoveEventHide

type DraggableMoveEvent<TSourcePayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
}

Draggable.MoveEventDetailsHide

type DraggableMoveEventDetails =
  { reason: 'pointer'; event: PointerEvent } | { reason: 'modifier-key'; event: KeyboardEvent }

Draggable.MoveStartContextHide

type DraggableMoveStartContext<TPayload = unknown, TDragData = unknown> = {
  /**
   * The source being picked up. The same record is used if the drag starts.
   * Call `updateDragData` to initialize gesture data before targets resolve and previews render.
   * A canceled pickup does not carry its gesture data into the next attempt.
   */
  source: DragSource<TPayload, TDragData>;
  /** 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;
}

Draggable.MoveStartEventHide

type DraggableMoveStartEvent<TSourcePayload = unknown, TDragData = unknown> = {
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TSourcePayload, TDragData>;
}

Draggable.MoveStartEventDetailsHide

type DraggableMoveStartEventDetails =
  | { reason: 'pointer'; event: PointerEvent }
  | { reason: 'double-click'; event: PointerEvent | MouseEvent }

DraggableCollisionHide

type DraggableCollision<TPayload = unknown, TDragData = unknown> = {
  /**
   * The item under the pointer. Use `payload` to identify it, and `getLocalPoint()`
   * or `getSnappedLocalPoint()` to decide on which side of it to insert.
   */
  target: DropTargetRecord<TPayload, TDragData>;
}

DraggableCollisionEndEventHide

type DraggableCollisionEndEvent<TPayload = unknown, TDragData = unknown> = {
  /**
   * The item under the pointer at release, or `null` when the drag was canceled,
   * released outside the group, or released over the dragged item.
   */
  collision: DraggableCollision<TPayload, TDragData> | null;
  /** The collision reported by the previous `onCollisionChange` call, or `null` before the first. */
  previousCollision: DraggableCollision<TPayload, TDragData> | null;
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
  /**
   * Whether the drag was canceled rather than released. A release outside any drop
   * target isn't a cancellation. Read `eventDetails.reason` for the exact outcome.
   */
  canceled: boolean;
  /**
   * The drop target that received the drop, or `null` when the drag was released
   * outside any target or canceled.
   */
  dropTarget: DropTargetRecord | null;
}

DraggableCollisionEventHide

type DraggableCollisionEvent<TPayload = unknown, TDragData = unknown> = {
  /** The item under the pointer, or `null` when outside the group or over the dragged item. */
  collision: DraggableCollision<TPayload, TDragData> | null;
  /** The collision reported by the previous `onCollisionChange` call, or `null` before the first. */
  previousCollision: DraggableCollision<TPayload, TDragData> | null;
  /** The pointer position and drop targets, now and at previous moments of the drag. */
  location: DragLocationHistory;
  /** The item being dragged. */
  source: DragSource<TPayload, TDragData>;
}

DraggablePreviewTypedPropsHide

type DraggablePreviewTypedProps<TPayload, TDragData = unknown> = {
  /**
   * 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 show no preview. The drag still runs.
   * @default false
   */
  disabled?: boolean;
  /**
   * One or more modifiers that constrain the preview only. The drop position still
   * follows the pointer. To constrain the drag itself, use `modifiers` on `Draggable.Root`.
   */
  modifiers?: DragModifiers;
  /**
   * Where the preview sits relative to the pointer.
   * @default 'source'
   */
  offset?: DragPreviewOffset;
  /**
   * Where to insert the preview element in the DOM. Defaults to beside the source,
   * so the same CSS applies to it. Pass a container to keep selectors such as
   * `:last-child` on the source's siblings unchanged during the drag.
   */
  container?: DragPreviewContainer;
  /**
   * The kind of the dragged item, which types `source.payload` in the render function.
   * Drags of other kinds show no preview.
   */
  kind: DragKind<TPayload, TDragData>;
  /**
   * The preview content. Pass a function to build the content from the drag source
   * when the drag starts. It can return `null` to show no preview for that drag.
   */
  children?:
    | React.ReactNode
    | ((parameters: DragPreviewRenderEvent<TPayload, TDragData>) => React.ReactNode);
}

RegisterAutoScrollerParametersHide

type RegisterAutoScrollerParameters<TSourcePayload = unknown, TDragData = unknown> = {
  /**
   * How far outside the container a drag can continue auto-scrolling, in CSS pixels.
   * A number applies to every edge; an object sets physical edges independently.
   * Omitted, negative, and non-finite edge values are treated as `0`.
   * Outside an edge, scrolling keeps its maximum engagement and existing speed ramp.
   * Viewports containing the drag position take priority over outside margins.
   * Does not change drop targets, layout, or document/page scrolling.
   * @default 0
   */
  overflowMargin?: AutoScrollOverflowMargin;
  accept?: DragAccept<TSourcePayload, TDragData>;
  /**
   * Whether auto-scrolling is disabled. An ancestor viewport can then scroll instead.
   * Changing it during a drag pauses or resumes scrolling.
   * Use `onDragScroll` for a decision that depends on the drag.
   * @default false
   */
  disabled?: boolean;
  /**
   * The scrolling speed reached at the container's edge, in pixels per second.
   * Accepts a number or a function called on every scrolling frame.
   * `0` stops this container and lets an ancestor viewport scroll instead.
   * @default 900
   */
  maxSpeed?:
    number | ((parameters: DragAutoScrollFrameContext<TSourcePayload, TDragData>) => number);
  /**
   * Event handler called once per direction on every scrolling frame.
   * Call `eventDetails.cancel()` to prevent scrolling in that direction, or to apply
   * the movement yourself for an element Base UI can't scroll, such as a panned canvas.
   * After moving, call `eventDetails.consume()` to keep an ancestor viewport from
   * scrolling on the same axis. Skip it at a bound the element can't move past.
   */
  onDragScroll?: DragAutoScrollHandler<TSourcePayload, TDragData>;
}

RegisterDraggableParametersHide

type RegisterDraggableParameters<TPayload = undefined, TDragData = unknown> = {
  /**
   * The data attached to this item, available as `source.payload` in every drag
   * event and drop target handler.
   */
  payload?: TPayload;
  /**
   * A stable key that lets the settling preview find this item again after it remounts,
   * for example when a virtualized or reordered list recreates it.
   * Use the same key for the same item.
   */
  previewKey?: string | number;
  /**
   * The kind of this item, created with `Draggable.createKind`. Drop targets and
   * monitors list the kinds they accept in `accept`. It determines the type of `payload`.
   */
  kind: DragKind<TPayload, TDragData>;
  /**
   * The element that must be pressed to start a drag. Accepts an element, a ref,
   * or a function returning one. It should exist when the item is registered.
   *
   * For sources registered with `registerDraggable`. `<Draggable.Root>` uses
   * `<Draggable.Handle>` instead.
   */
  dragHandle?: DragHandle;
  /**
   * Whether dragging is disabled. Pointer presses keep their normal behavior.
   * Use `onBeforeMoveStart` when the decision depends on the gesture.
   * @default false
   */
  disabled?: boolean;
  /**
   * Event handler called just before a drag starts, once the activation threshold is met.
   * Call `eventDetails.cancel()` to prevent the drag.
   */
  onBeforeMoveStart?: (
    context: MoveStartContext<TPayload, TDragData>,
    eventDetails: BeforeMoveStartEventDetails,
  ) => void;
  /**
   * Determines when a pointer press starts a drag. Accepts one activation method for
   * every pointer type, a map with a method per pointer type, or an array to allow
   * several methods. By default, mouse and pen start after 5px of movement, and touch
   * after a 250ms hold.
   */
  activation?: DragActivationConfig | DragActivationConfig[];
  /**
   * One or more modifiers that constrain the drag, applied in order.
   * They affect both the preview and the drop position.
   * See [Constraining movement](https://base-ui.com/react/utils/draggable#constraining-movement).
   */
  modifiers?: DragModifiers;
  /**
   * The CSS cursor shown across the document during a mouse or pen drag.
   * Pass `false` to manage the cursor yourself.
   * @default 'grabbing'
   */
  dragCursor?: string | false;
  /**
   * The drag preview of this item. Omit it to use a clone of the source.
   *
   * For sources registered with `registerDraggable`. `<Draggable.Root>` uses
   * `<Draggable.Preview>` instead.
   */
  dragPreview?: DragPreviewParameters<TPayload, TDragData>;
  /**
   * Event handler called once when the drag starts. The preview exists by then,
   * so the source can be measured or restyled safely.
   */
  onMoveStart?: (
    parameters: MoveStartEvent<TPayload, TDragData>,
    eventDetails: MoveStartEventDetails,
  ) => void;
  /**
   * Event handler called as the pointer moves or a modifier key changes,
   * at most once per animation frame. Use a drop target's `onDraggableMove`
   * for hover feedback.
   */
  onMove?: (parameters: MoveEvent<TPayload, TDragData>, eventDetails: MoveEventDetails) => void;
  /** Event handler called when the drop targets under the pointer change. */
  onTargetChange?: (
    parameters: DropTargetChangeEvent<TPayload, TDragData>,
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called once when the drag ends, after a drop, a release outside any
   * target, or a cancellation. `eventDetails.reason` is `'drop'` for a successful drop.
   *
   * A drag canceled during pickup fires this handler without a preceding `onMoveStart`.
   */
  onMoveEnd?: (
    parameters: MoveEndEvent<TPayload, TDragData>,
    eventDetails: MoveEndEventDetails,
  ) => void;
}

RegisterDraggableParametersWithPayloadHide

type RegisterDraggableParametersWithPayload<TPayload, TDragData = unknown> = {
  payload: TPayload;
  /**
   * A stable key that lets the settling preview find this item again after it remounts,
   * for example when a virtualized or reordered list recreates it.
   * Use the same key for the same item.
   */
  previewKey?: string | number;
  /**
   * The kind of this item, created with `Draggable.createKind`. Drop targets and
   * monitors list the kinds they accept in `accept`. It determines the type of `payload`.
   */
  kind: DragKind<TPayload, TDragData>;
  /**
   * The element that must be pressed to start a drag. Accepts an element, a ref,
   * or a function returning one. It should exist when the item is registered.
   *
   * For sources registered with `registerDraggable`. `<Draggable.Root>` uses
   * `<Draggable.Handle>` instead.
   */
  dragHandle?: DragHandle;
  /**
   * Whether dragging is disabled. Pointer presses keep their normal behavior.
   * Use `onBeforeMoveStart` when the decision depends on the gesture.
   * @default false
   */
  disabled?: boolean;
  /**
   * Event handler called just before a drag starts, once the activation threshold is met.
   * Call `eventDetails.cancel()` to prevent the drag.
   */
  onBeforeMoveStart?: (
    context: MoveStartContext<TPayload, TDragData>,
    eventDetails: BeforeMoveStartEventDetails,
  ) => void;
  /**
   * Determines when a pointer press starts a drag. Accepts one activation method for
   * every pointer type, a map with a method per pointer type, or an array to allow
   * several methods. By default, mouse and pen start after 5px of movement, and touch
   * after a 250ms hold.
   */
  activation?: DragActivationConfig | DragActivationConfig[];
  /**
   * One or more modifiers that constrain the drag, applied in order.
   * They affect both the preview and the drop position.
   * See [Constraining movement](https://base-ui.com/react/utils/draggable#constraining-movement).
   */
  modifiers?: DragModifiers;
  /**
   * The CSS cursor shown across the document during a mouse or pen drag.
   * Pass `false` to manage the cursor yourself.
   * @default 'grabbing'
   */
  dragCursor?: string | false;
  /**
   * The drag preview of this item. Omit it to use a clone of the source.
   *
   * For sources registered with `registerDraggable`. `<Draggable.Root>` uses
   * `<Draggable.Preview>` instead.
   */
  dragPreview?: DragPreviewParameters<TPayload, TDragData>;
  /**
   * Event handler called once when the drag starts. The preview exists by then,
   * so the source can be measured or restyled safely.
   */
  onMoveStart?: (
    parameters: MoveStartEvent<TPayload, TDragData>,
    eventDetails: MoveStartEventDetails,
  ) => void;
  /**
   * Event handler called as the pointer moves or a modifier key changes,
   * at most once per animation frame. Use a drop target's `onDraggableMove`
   * for hover feedback.
   */
  onMove?: (parameters: MoveEvent<TPayload, TDragData>, eventDetails: MoveEventDetails) => void;
  /** Event handler called when the drop targets under the pointer change. */
  onTargetChange?: (
    parameters: DropTargetChangeEvent<TPayload, TDragData>,
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called once when the drag ends, after a drop, a release outside any
   * target, or a cancellation. `eventDetails.reason` is `'drop'` for a successful drop.
   *
   * A drag canceled during pickup fires this handler without a preceding `onMoveStart`.
   */
  onMoveEnd?: (
    parameters: MoveEndEvent<TPayload, TDragData>,
    eventDetails: MoveEndEventDetails,
  ) => void;
}

RegisterDropTargetParametersHide

type RegisterDropTargetParameters<
  TSourcePayload = unknown,
  TTargetPayload = unknown,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  /**
   * The data attached to this target, available as `target.payload` in its handlers
   * and on its record in `location.current.dropTargets`.
   */
  payload?: TTargetPayload;
  /**
   * The kind of this target, created with `Draggable.createKind`. Use its `matches`
   * method to tell target kinds apart in a shared handler, which also types
   * `target.payload`. Not to be confused with `accept`, which lists the kinds of
   * draggable this target takes.
   */
  kind?: DragKind<TTargetPayload, TTargetDragData>;
  /**
   * Whether the target ignores drags. A disabled target is skipped, so drags fall
   * through to ancestor targets.
   * @default false
   */
  disabled?: boolean;
  /**
   * Divides the target into equal steps for `getSnappedLocalPoint()`. For example,
   * `{ y: 96 }` splits a day column into 15-minute slots, whatever its height.
   * Accepts step counts or a function receiving the drag source.
   *
   * It only changes the value this target reports. Use the `snapToGrid` modifier
   * to snap the preview itself.
   */
  snap?:
    | DragSnapSteps
    | ((
        context: DropTargetResolutionContext<TSourcePayload, TDragData>,
      ) => DragSnapSteps | undefined);
  /**
   * Event handler called when the drag is released over this target. Only the innermost
   * target under the pointer receives it, and it never fires on a cancel.
   * Use the source's or a monitor's `onMoveEnd` to observe every drag end.
   */
  onDraggableDrop?: (
    parameters: DropEvent<TSourcePayload, TTargetPayload, TDragData, TTargetDragData>,
    eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent },
  ) => void;
  /**
   * Event handler called when a drag starts while this target is already under the
   * pointer. Use a monitor's `onMoveStart` to observe drags starting elsewhere.
   */
  onDraggableStart?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: MoveStartEventDetails,
  ) => void;
  /**
   * Event handler called on every animation frame the pointer moves or a modifier key
   * changes while the drag is over this target, starting with the frame it enters.
   * Put hover feedback such as drop indicators here.
   */
  onDraggableMove?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: MoveEventDetails,
  ) => void;
  /** Event handler called when the drag moves over this target. */
  onDraggableEnter?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called when the drag moves off this target, or ends.
   * `eventDetails.reason` tells which.
   */
  onDraggableLeave?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Decides whether the current drag can be dropped on this target. Runs after `accept`.
   *
   * Return `false` to skip this target and let an ancestor receive the drop.
   * Return `'reject'` to block the drop on this target, its nested targets, and its
   * ancestors, for example when a column is full. The target then has `[data-rejected]`.
   */
  canDrop?: (
    parameters: DropTargetResolutionContext<TSourcePayload, TDragData>,
  ) => boolean | 'reject';
  /**
   * One or more kinds of draggable this target accepts. Pass `Draggable.anyKind`
   * to accept every drag, with `source.payload` typed as `unknown`.
   *
   * Drags of other kinds ignore this target, but an ancestor target can still accept them.
   */
  accept: NonNullable<DragAccept<TSourcePayload, TDragData> | undefined>;
}

RegisterDropTargetParametersWithPayloadHide

type RegisterDropTargetParametersWithPayload<
  TSourcePayload,
  TTargetPayload,
  TDragData = unknown,
  TTargetDragData = unknown,
> = {
  payload: TTargetPayload;
  /**
   * The kind of this target, created with `Draggable.createKind`. Use its `matches`
   * method to tell target kinds apart in a shared handler, which also types
   * `target.payload`. Not to be confused with `accept`, which lists the kinds of
   * draggable this target takes.
   */
  kind?: DragKind<TTargetPayload, TTargetDragData>;
  /**
   * Whether the target ignores drags. A disabled target is skipped, so drags fall
   * through to ancestor targets.
   * @default false
   */
  disabled?: boolean;
  /**
   * Divides the target into equal steps for `getSnappedLocalPoint()`. For example,
   * `{ y: 96 }` splits a day column into 15-minute slots, whatever its height.
   * Accepts step counts or a function receiving the drag source.
   *
   * It only changes the value this target reports. Use the `snapToGrid` modifier
   * to snap the preview itself.
   */
  snap?:
    | DragSnapSteps
    | ((
        context: DropTargetResolutionContext<TSourcePayload, TDragData>,
      ) => DragSnapSteps | undefined);
  /**
   * Event handler called when the drag is released over this target. Only the innermost
   * target under the pointer receives it, and it never fires on a cancel.
   * Use the source's or a monitor's `onMoveEnd` to observe every drag end.
   */
  onDraggableDrop?: (
    parameters: DropEvent<TSourcePayload, TTargetPayload, TDragData, TTargetDragData>,
    eventDetails: { reason: 'drop'; event: PointerEvent | MouseEvent },
  ) => void;
  /**
   * Event handler called when a drag starts while this target is already under the
   * pointer. Use a monitor's `onMoveStart` to observe drags starting elsewhere.
   */
  onDraggableStart?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: MoveStartEventDetails,
  ) => void;
  /**
   * Event handler called on every animation frame the pointer moves or a modifier key
   * changes while the drag is over this target, starting with the frame it enters.
   * Put hover feedback such as drop indicators here.
   */
  onDraggableMove?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: MoveEventDetails,
  ) => void;
  /** Event handler called when the drag moves over this target. */
  onDraggableEnter?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called when the drag moves off this target, or ends.
   * `eventDetails.reason` tells which.
   */
  onDraggableLeave?: (
    parameters: {
      location: DragLocationHistory;
      source: DragSource<TSourcePayload, TDragData>;
      target: DropTargetRecord<TTargetPayload, TTargetDragData>;
    },
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Decides whether the current drag can be dropped on this target. Runs after `accept`.
   *
   * Return `false` to skip this target and let an ancestor receive the drop.
   * Return `'reject'` to block the drop on this target, its nested targets, and its
   * ancestors, for example when a column is full. The target then has `[data-rejected]`.
   */
  canDrop?: (
    parameters: DropTargetResolutionContext<TSourcePayload, TDragData>,
  ) => boolean | 'reject';
  /**
   * One or more kinds of draggable this target accepts. Pass `Draggable.anyKind`
   * to accept every drag, with `source.payload` typed as `unknown`.
   *
   * Drags of other kinds ignore this target, but an ancestor target can still accept them.
   */
  accept: NonNullable<DragAccept<TSourcePayload, TDragData> | undefined>;
}

RegisterMonitorParametersHide

type RegisterMonitorParameters<TSourcePayload = unknown, TDragData = unknown> = {
  accept?: DragAccept<TSourcePayload, TDragData>;
  /**
   * Event handler called once when a matching drag starts, wherever it started.
   * A monitor registered during a drag doesn't receive it for that drag.
   */
  onMoveStart?: (
    parameters: MoveStartEvent<TSourcePayload, TDragData>,
    eventDetails: MoveStartEventDetails,
  ) => void;
  /**
   * Event handler called as the pointer moves or a modifier key changes,
   * at most once per animation frame.
   */
  onMove?: (
    parameters: MoveEvent<TSourcePayload, TDragData>,
    eventDetails: MoveEventDetails,
  ) => void;
  /** Event handler called when the drop targets under the pointer change. */
  onTargetChange?: (
    parameters: DropTargetChangeEvent<TSourcePayload, TDragData>,
    eventDetails: DropTargetChangeEventDetails,
  ) => void;
  /**
   * Event handler called once when the drag ends, after a drop, a release outside any
   * target, or a cancellation. `eventDetails.reason` identifies the outcome, and
   * `dropTarget` is the target of a drop, or `null`.
   *
   * It can fire without a preceding `onMoveStart`, for example when the monitor
   * registered during the drag, so don't assume the two are paired.
   */
  onMoveEnd?: (
    parameters: MoveEndEvent<TSourcePayload, TDragData>,
    eventDetails: MoveEndEventDetails,
  ) => void;
}

UseActiveDragReturnValueHide

type UseActiveDragReturnValue<TPayload = unknown, TDragData = unknown> = DragSource<
  TPayload,
  TDragData
> | null

UseDragDropManagerReturnValueHide

type UseDragDropManagerReturnValue = {
  /**
   * Registers an element as a drag source, with the options of `Draggable.Root`.
   * Returns a cleanup function that unregisters it.
   */
  registerDraggable:
    | (<TPayload, TDragData = unknown>(
        element: HTMLElement,
        getParameters: () => RegisterDraggableParametersWithPayload<TPayload, TDragData>,
      ) => (() => void))
    | (<TKind extends DragKind<undefined, any> = DragKind<undefined, unknown>>(
        element: HTMLElement,
        getParameters: () => {
          payload?: undefined;
          previewKey?: string | number;
          dragHandle?: DragHandle;
          disabled?: boolean;
          onBeforeMoveStart?: (
            context: MoveStartContext<undefined, TDragData | unknown>,
            eventDetails: BeforeMoveStartEventDetails,
          ) => void;
          activation?: DragActivationConfig | DragActivationConfig[];
          modifiers?: DragModifiers;
          dragCursor?: string | false;
          dragPreview?: DragPreviewParameters<undefined, TDragData | unknown>;
          onMoveStart?: (
            parameters: MoveStartEvent<undefined, TDragData | unknown>,
            eventDetails: MoveStartEventDetails,
          ) => void;
          onMove?: (
            parameters: MoveEvent<undefined, TDragData | unknown>,
            eventDetails: MoveEventDetails,
          ) => void;
          onTargetChange?: (
            parameters: DropTargetChangeEvent<undefined, TDragData | unknown>,
            eventDetails: DropTargetChangeEventDetails,
          ) => void;
          onMoveEnd?: (
            parameters: MoveEndEvent<undefined, TDragData | unknown>,
            eventDetails: MoveEndEventDetails,
          ) => void;
          kind: TKind;
        },
      ) => (() => void));
  /**
   * Registers an element as a drop target, with the options of `Draggable.Target`.
   * Returns a cleanup function that unregisters it.
   */
  registerDropTarget: <
    TAccept extends AnyDragAccept = DragKind,
    TTargetPayload = undefined,
    TKind extends DragKind<TTargetPayload, any> | undefined =
      DragKind<TTargetPayload, unknown> | undefined,
  >(
    element: HTMLElement,
    getParameters: () => Omit<
      RegisterDropTargetParameters<
        TPayload | unknown,
        TTargetPayload,
        TDragData | unknown,
        TDragData | unknown
      >,
      'kind'
    > & { accept: TAccept } & DragParametersWithTargetKind<TKind> &
      ({} | { payload: TTargetPayload }),
  ) => (() => void);
  /**
   * Registers a scroll container, with the options of `Draggable.Viewport`.
   * Pass `document.documentElement` to scroll the page.
   * Returns a cleanup function that unregisters it.
   */
  registerAutoScroller: <TAccept extends AnyDragAccept = DragKind>(
    element: HTMLElement,
    getParameters: () => DragParametersWithInferredAccept<
      RegisterAutoScrollerParameters<TPayload | unknown, TDragData | unknown>,
      TAccept
    >,
  ) => (() => void);
  /**
   * Registers a monitor, with the options of `useDragMonitor`.
   * Returns a cleanup function that unregisters it.
   */
  registerMonitor: <TAccept extends AnyDragAccept = DragKind>(
    getParameters: () => DragParametersWithInferredAccept<
      RegisterMonitorParameters<TPayload | unknown, TDragData | unknown>,
      TAccept
    >,
  ) => (() => void);
  /**
   * Cancels the drag in progress, if any. `onMoveEnd` fires with `canceled: true`
   * and the `'imperative-action'` reason.
   */
  cancelDrag: () => void;
}

UseDragMonitorParametersHide

type UseDragMonitorParameters<
  TSourcePayload = unknown,
  TDragData = unknown,
> = RegisterMonitorParameters<TSourcePayload, TDragData>