('item');
}
/>;
```
The [sortable list example](/react/drag-and-drop/overview.md) builds a full reorderable list on top of this.
## API reference
The dragged item's payload type and this target's payload flow through every event: a
target with an `accept` and a `payload` hands both to `onDrop`, `canDrop`, and the
rest. The generated tables below render those signatures at the _default_ types
(`unknown`/`undefined`, or `any` where both overloads are shown), because the
reference is extracted without concrete type arguments. Read them as "what this
target's `accept` and `payload` resolve to".
### Root
Makes its element a drop target, so matching drag sources can be released on it.
Renders a `` element.
**Root Props:**
| Prop | Type | Default | Description |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| label | `string` | - | Human-readable name of this drop target, used by the default screen-reader
announcements for keyboard drags to name where the item is and where it landed. |
| accept\* | `NonNullable \| undefined> \| DragKind & AnyDragAccept \| (DragKind)[] & AnyDragAccept` | - | - |
| canDrop | `((parameters: DropTargetResolutionContext) => boolean \| 'reject') \| ((parameters: DropTargetResolutionContext) => boolean \| 'reject')` | - | Predicate for whether this target should be considered a candidate for the
current drag. Runs after `accept`. Return `false` to skip this target for the current resolution. Base UI continues
through its ancestors, so a parent target can receive the drop. This differs from
ignoring the drop inside `onDrop`, which does not give a parent target a chance. Return `'reject'` to block every drop at this position. Descendants, this target,
and ancestors cannot receive the drop. While the drag is over the target, it has
`data-rejected`. Use this for container rules such as a capacity limit. Returning
`false` would allow an item inside the container to receive the drop. |
| getPayload | `DropTargetPayloadGetter \| ((context: DropTargetResolutionContext) => undefined) \| DropTargetPayloadGetter \| ((context: DropTargetResolutionContext) => undefined)` | - | Resolves payload data from the current drag context. |
| kind | `DragKind \| DragKind` | - | The target kind created with `Draggable.createKind`. It is available as
`self.kind` and on entries in `location.dropTargets`. Use the kind's `matches`
method to distinguish target kinds and narrow their payload types. Its payload
type must match this target's `payload`. Distinct from `accept`, which declares the **source** kinds this target takes. |
| onDrag | `((parameters: DropTargetEvent<'onDrag', TSourceData, TLocalData>, eventDetails: DragMoveEventDetails) => void) \| ((parameters: DropTargetEvent<'onDrag', TSourceData, undefined>, eventDetails: DragMoveEventDetails) => void) \| ((parameters: DropTargetEvent<'onDrag', TPayload \| unknown, TLocalData>, eventDetails: DragMoveEventDetails) => void) \| ((parameters: DropTargetEvent<'onDrag', TPayload \| unknown, undefined>, eventDetails: DragMoveEventDetails) => void)` | - | Event handler called on the frame this target enters the active stack, right
after `onDragEnter`, and on every rAF tick the pointer moves while the target
remains in the stack. Put hover-tracking work here and use `onDragEnter` for
enter-only side effects. |
| onDragEnter | `((parameters: DropTargetEvent<'onDragEnter', TSourceData, TLocalData>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragEnter', TSourceData, undefined>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragEnter', TPayload \| unknown, TLocalData>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragEnter', TPayload \| unknown, undefined>, eventDetails: DropTargetChangeEventDetails) => void)` | - | Event handler called when this target enters the active stack. |
| onDragLeave | `((parameters: DropTargetEvent<'onDragLeave', TSourceData, TLocalData>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragLeave', TSourceData, undefined>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragLeave', TPayload \| unknown, TLocalData>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragLeave', TPayload \| unknown, undefined>, eventDetails: DropTargetChangeEventDetails) => void)` | - | Event handler called when this target leaves the active stack, because the
pointer moved away or the drag ended. `eventDetails.reason` identifies whether
the pointer or keyboard left the target, or the drag ended. |
| onDragStart | `((parameters: DropTargetEvent<'onDragStart', TSourceData, TLocalData>, eventDetails: DragStartEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragStart', TSourceData, undefined>, eventDetails: DragStartEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragStart', TPayload \| unknown, TLocalData>, eventDetails: DragStartEventDetails) => void) \| ((parameters: DropTargetEvent<'onDragStart', TPayload \| unknown, undefined>, eventDetails: DragStartEventDetails) => void)` | - | Event handler called when a matching drag starts while this target is already
under the pointer. It does not fire for drags that start elsewhere; use a
monitor's `onDragStart` to observe every drag. |
| onDrop | `((parameters: DropEvent, eventDetails: { reason: 'drop'; event: PointerEvent \| KeyboardEvent }) => void) \| ((parameters: DropEvent, eventDetails: { reason: 'drop'; event: PointerEvent \| KeyboardEvent }) => void) \| ((parameters: DropEvent, eventDetails: { reason: 'drop'; event: PointerEvent \| KeyboardEvent }) => void) \| ((parameters: DropEvent, eventDetails: { reason: 'drop'; event: PointerEvent \| KeyboardEvent }) => void)` | - | Event handler called on the innermost active drop target only, when the user
releases the drag over it. Ancestor targets in the same stack do not receive
`onDrop`, and it never fires on a cancel. To observe every drag end regardless of
target depth or cancellation, use the source's or a monitor's `onDragEnd`. |
| onDropTargetChange | `((parameters: DropTargetEvent<'onDropTargetChange', TSourceData, TLocalData>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDropTargetChange', TSourceData, undefined>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDropTargetChange', TPayload \| unknown, TLocalData>, eventDetails: DropTargetChangeEventDetails) => void) \| ((parameters: DropTargetEvent<'onDropTargetChange', TPayload \| unknown, undefined>, eventDetails: DropTargetChangeEventDetails) => void)` | - | Event handler called when the active drop targets change, including changes that
don't affect this target's own membership, such as a nested descendant entering
or leaving while this ancestor stays in the stack. Use `onDragEnter` and
`onDragLeave` for this target's own enter and leave. |
| payload | `TLocalData` | - | Static payload data. Function values are preserved without being invoked. |
| snap | `DragSnapSteps \| ((context: DropTargetResolutionContext) => DragSnapSteps \| undefined) \| ((context: DropTargetResolutionContext) => DragSnapSteps \| undefined)` | - | Divides the target's border box into equal steps for
`getSnappedLocalPoint()`. For example, `{ y: 96 }` creates 15-minute slots in
a day column, and `{ x: 7, y: 6 }` creates a month grid. Step counts do not depend on the target's pixel size. Base UI measures the
target when resolving a drag. Pass a static value or a callback that receives
the same context as `canDrop`. The callback runs on the first snapped read for
each resolution. Return `undefined` to skip snapping. This differs from `snapToGrid`, which snaps the drag position for every target.
`snap` changes only the value reported by this target. |
| trackDragOver | `boolean` | `true` | Whether to update drag-over state and its data attributes. Set to `false`
when the target renders no drag-over feedback; drag callbacks still fire. |
| disabled | `boolean` | `false` | Whether the drop target should ignore user interaction. A disabled target is
skipped by target resolution as if it weren't registered, so drags fall through
to ancestor targets. A hovered target disabled mid-drag leaves the active stack,
with its `onDragLeave`, on the next resolution. |
| className | `string \| ((state: DropTarget.Root.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: DropTarget.Root.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: DropTarget.Root.State) => ReactElement)` | - | 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. |
**Root Data Attributes:**
| Attribute | Type | 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`. |
### Root.Props
Re-export of [Root](/react/components/drop-target.md) props.
### Root.State
```typescript
type DropTargetRootState = {
/**
* Whether a matching drag source is currently over this target or a nested
* descendant. Always `false` when `trackDragOver` is `false`.
*/
dragOver: boolean;
/**
* Whether this target accepts the current drag, regardless of pointer position.
* Use it to highlight all compatible drop targets. It is `false` when no drag is
* active, the target is disabled, or `trackDragOver` is `false`. The value is
* based on `accept`; `canDrop` is evaluated only for the current position.
*/
accepting: boolean;
/**
* Whether this is the innermost active target. A nested ancestor has `dragOver`
* true but `dragOverInnermost` false while a descendant target is active. Always
* `false` when `trackDragOver` is `false`.
*/
dragOverInnermost: boolean;
/**
* Whether `canDrop` returned `'reject'` for the current position. Use it to
* display feedback such as a full column. It is mutually exclusive with
* `dragOver` and always `false` when `trackDragOver` is `false`.
*/
rejected: boolean;
/** Whether the drop target is disabled. */
disabled: boolean;
};
```
### Root.PropsWithPayload
```typescript
type DropTargetRootPropsWithPayload = (
| { payload: TLocalData; getPayload?: undefined }
| { payload?: undefined; getPayload: DropTargetPayloadGetter }
) & {
/**
* CSS class applied to the element, or a function that
* returns a class based on the component's state.
*/
className?: string | ((state: DropTarget.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: DropTarget.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: DropTarget.Root.State) => ReactElement);
/**
* Human-readable name of this drop target, used by the default screen-reader
* announcements for keyboard drags to name where the item is and where it landed.
*/
label?: string;
/**
* Event handler called on the frame this target enters the active stack, right
* after `onDragEnter`, and on every rAF tick the pointer moves while the target
* remains in the stack. Put hover-tracking work here and use `onDragEnter` for
* enter-only side effects.
*/
onDrag?: (
parameters: DropTargetEvent<'onDrag', TSourceData, TLocalData>,
eventDetails: DragMoveEventDetails,
) => void;
/** Event handler called when this target enters the active stack. */
onDragEnter?: (
parameters: DropTargetEvent<'onDragEnter', TSourceData, TLocalData>,
eventDetails: DropTargetChangeEventDetails,
) => void;
/**
* Event handler called when this target leaves the active stack, because the
* pointer moved away or the drag ended. `eventDetails.reason` identifies whether
* the pointer or keyboard left the target, or the drag ended.
*/
onDragLeave?: (
parameters: DropTargetEvent<'onDragLeave', TSourceData, TLocalData>,
eventDetails: DropTargetChangeEventDetails,
) => void;
/**
* Event handler called when a matching drag starts while this target is already
* under the pointer. It does not fire for drags that start elsewhere; use a
* monitor's `onDragStart` to observe every drag.
*/
onDragStart?: (
parameters: DropTargetEvent<'onDragStart', TSourceData, TLocalData>,
eventDetails: DragStartEventDetails,
) => void;
/**
* Event handler called on the innermost active drop target only, when the user
* releases the drag over it. Ancestor targets in the same stack do not receive
* `onDrop`, and it never fires on a cancel. To observe every drag end regardless of
* target depth or cancellation, use the source's or a monitor's `onDragEnd`.
*/
onDrop?: (
parameters: DropEvent,
eventDetails: { reason: 'drop'; event: PointerEvent | KeyboardEvent },
) => void;
accept: NonNullable | undefined>;
/**
* The target kind created with `Draggable.createKind`. It is available as
* `self.kind` and on entries in `location.dropTargets`. Use the kind's `matches`
* method to distinguish target kinds and narrow their payload types. Its payload
* type must match this target's `payload`.
*
* Distinct from `accept`, which declares the **source** kinds this target takes.
*/
kind?: DragKind;
/**
* Whether the drop target should ignore user interaction. A disabled target is
* skipped by target resolution as if it weren't registered, so drags fall through
* to ancestor targets. A hovered target disabled mid-drag leaves the active stack,
* with its `onDragLeave`, on the next resolution.
* @default false
*/
disabled?: boolean;
/**
* Predicate for whether this target should be considered a candidate for the
* current drag. Runs after `accept`.
*
* Return `false` to skip this target for the current resolution. Base UI continues
* through its ancestors, so a parent target can receive the drop. This differs from
* ignoring the drop inside `onDrop`, which does not give a parent target a chance.
*
* Return `'reject'` to block every drop at this position. Descendants, this target,
* and ancestors cannot receive the drop. While the drag is over the target, it has
* `data-rejected`. Use this for container rules such as a capacity limit. Returning
* `false` would allow an item inside the container to receive the drop.
*/
canDrop?: (parameters: DropTargetResolutionContext) => boolean | 'reject';
/**
* Divides the target's border box into equal steps for
* `getSnappedLocalPoint()`. For example, `{ y: 96 }` creates 15-minute slots in
* a day column, and `{ x: 7, y: 6 }` creates a month grid.
*
* Step counts do not depend on the target's pixel size. Base UI measures the
* target when resolving a drag. Pass a static value or a callback that receives
* the same context as `canDrop`. The callback runs on the first snapped read for
* each resolution. Return `undefined` to skip snapping.
*
* This differs from `snapToGrid`, which snaps the drag position for every target.
* `snap` changes only the value reported by this target.
*/
snap?:
| DragSnapSteps
| ((context: DropTargetResolutionContext) => DragSnapSteps | undefined);
/**
* Event handler called when the active drop targets change, including changes that
* don't affect this target's own membership, such as a nested descendant entering
* or leaving while this ancestor stays in the stack. Use `onDragEnter` and
* `onDragLeave` for this target's own enter and leave.
*/
onDropTargetChange?: (
parameters: DropTargetEvent<'onDropTargetChange', TSourceData, TLocalData>,
eventDetails: DropTargetChangeEventDetails,
) => void;
/**
* Whether to update drag-over state and its data attributes. Set to `false`
* when the target renders no drag-over feedback; drag callbacks still fire.
* @default true
*/
trackDragOver?: boolean;
accept: NonNullable | undefined>;
};
```
### createGlobalKind
Creates a globally interned drag kind for integrations where independently evaluated
bundles must match without sharing the same kind value.
```ts
const card = Draggable.createGlobalKind('myapp/card');
```
The key is the runtime identity, so every call with the same key matches, including
calls made by another copy of the bundle. It must be namespaced (for example,
`'myapp/card'`) because using the same key with incompatible payload types bypasses
TypeScript and causes the integrations to exchange the wrong payload at runtime.
Prefer [`createKind`](/react/components/drop-target.md) when the kind value can be shared directly.
**Parameters:**
| Parameter | Type | Default | Description |
| :-------- | :------- | :------ | :---------------------------------------------- |
| key | `string` | - | A namespaced global key such as `'myapp/card'`. |
**Return Value:**
```tsx
type ReturnValue = DragKind;
```
### createKind
Creates a drag kind to pass to a draggable's `kind` and a drop target's
`accept`.
```ts
const card = Draggable.createKind('card');
```
Each call creates a unique identity. Declare the kind once and share it with every
draggable and drop target in the interaction. The name is only a debugging aid.
Separate calls with the same name do not match.
Use [`createGlobalKind`](/react/components/drop-target.md) only when independently evaluated bundles deliberately
need to share a kind by a namespaced key.
**Parameters:**
| Parameter | Type | Default | Description |
| :-------- | :------- | :------ | :---------- |
| name | `string` | - | - |
**Return Value:**
```tsx
type ReturnValue = DragKind;
```
### DropTargetPayloadGetter
Resolves a drop target's payload each time the target is evaluated.
**Parameters:**
| Parameter | Type | Default | Description |
| :-------- | :----------------------------------------- | :------ | :---------- |
| context | `DropTargetResolutionContext` | - | - |
**Return Value:**
```tsx
type ReturnValue = TLocalData;
```
## Additional Types
### BaseDragEvent
Fields included in every drag-and-drop event.
```typescript
type BaseDragEvent = {
location: DragLocationHistory;
source: DragSource;
/**
* The input method driving the drag.
* This is the reliable way to detect a keyboard drag, as
* `location.current.input.pointerType` is `null` for those.
*/
mode: DragMode;
};
```
### DragAccept
One or more drag kinds accepted by a drop target or monitor. The accepted kinds
determine the type of `source.payload`.
```typescript
type DragAccept = DragKind | DragKind[];
```
### DragCanceledReason
Why a drag was aborted.
Escape and Tab represent deliberate user actions. The other reasons describe an
interrupted drag. Unless the distinction matters to your app, handle those reasons
together and include a default branch for reasons added in a future release.
- `'escape-key'` / `'tab-key'`: the user pressed Escape or Tab.
- `'pointer-down'`: the user pressed a pointer during a keyboard drag.
- `'focus-out'`: focus moved into a text input, which needs the keys the drag was swallowing.
- `'imperative-action'`: the application called `cancelDrag()`.
- `'window-blur'` / `'page-hidden'`: the window lost focus, or the page was hidden.
- `'pointer-canceled'`: the browser or OS canceled the pointer stream.
- `'capture-lost'`: pointer capture moved away mid-gesture.
- `'missed-release'`: the button came up without a terminating event reaching Base UI.
- `'handler-error'`: one of your own handlers threw, so Base UI ended the drag.
The original error is rethrown separately.
- `'document-detached'`: the drag's document lost its browsing context (iframe removed,
popout closed).
```typescript
type DragCanceledReason =
| 'escape-key'
| 'tab-key'
| 'pointer-down'
| 'focus-out'
| 'imperative-action'
| 'window-blur'
| 'page-hidden'
| 'pointer-canceled'
| 'capture-lost'
| 'missed-release'
| 'document-detached'
| 'handler-error';
```
### DragCompletedReason
Why a drag finished without being aborted.
- `'drop'`: released over an accepting drop target. `onDrop` fires for this one only.
- `'outside-release'`: released over no accepting target, so nothing was committed.
```typescript
type DragCompletedReason = 'drop' | 'outside-release';
```
### DragDropEvent
The event object passed to `onDrop`. This event fires only after release over an
accepting target, so `dropTarget` is never `null`. In a drop target's `onDrop`,
it is the same record as `self`.
```typescript
type DragDropEvent = {
location: DragLocationHistory;
source: DragSource;
/**
* The input method driving the drag.
* This is the reliable way to detect a keyboard drag, as
* `location.current.input.pointerType` is `null` for those.
*/
mode: DragMode;
dropTarget: DropTargetRecord;
};
```
### DragDropEventDetails
The event details passed to `onDrop`.
```typescript
type DragDropEventDetails = {
/** Why the event fired. */
reason: 'drop';
/**
* The native event behind the dispatch. Programmatic and lifecycle-only
* reasons carry a generic `Event` placeholder.
*/
event: PointerEvent | KeyboardEvent;
};
```
### DragDropReason
The reason passed to `onDrop`. Always `'drop'`.
```typescript
type DragDropReason = 'drop';
```
### DragEndReason
Why a drag ended, in full. `canceled` on the event is `reason` being a cancel one.
```typescript
type DragEndReason = DragCompletedReason | DragCanceledReason;
```
### DragEventDetails
The details of a drag event, passed as the second argument to every handler.
Contains the event `reason` and native `event`, which are not included in the
first handler argument. These events cannot be canceled because Base UI has
already applied the action. Use `onBeforeDragStart` to cancel a drag pickup.
```typescript
type DragEventDetails = {
/** Why the event fired. */
reason: TReason;
/**
* The native event behind the dispatch. Programmatic and lifecycle-only
* reasons carry a generic `Event` placeholder.
*/
event: PointerEvent | KeyboardEvent | FocusEvent | Event;
};
```
### DragEventDetailsMap
Maps each drag event to the details object its handler receives second.
The parallel of [`DragEventMap`](/react/components/drop-target.md), which maps them to their payloads.
```typescript
type DragEventDetailsMap = {
onDragStart: DragStartEventDetails;
onDrag: DragMoveEventDetails;
onDropTargetChange: DropTargetChangeEventDetails;
onDragEnter: DropTargetChangeEventDetails;
onDragLeave: DropTargetChangeEventDetails;
onDrop: DragDropEventDetails;
onDragEnd: DragEndEventDetails;
};
```
### DragEventMap
The event object of each drag-and-drop event, indexed by the event name.
`DragEventMap['onDrag']` is the event object passed to `onDrag` callbacks.
For a drop target's handlers use [`DropTargetEvent`](/react/components/drop-target.md) (or [`DropEvent`](/react/components/drop-target.md)),
which add the target's own `self` record.
```typescript
type DragEventMap = {
onDragStart: DragStartEvent;
onDrag: DragMoveEvent;
onDropTargetChange: DropTargetChangeEvent;
onDragEnter: BaseDragEvent;
onDragLeave: BaseDragEvent;
onDrop: DragDropEvent;
onDragEnd: DragEndEvent;
};
```
### DragInput
Pointer state captured at the moment a drag-and-drop event fires.
```typescript
type DragInput = {
/**
* `MouseEvent.button` semantics: 0 = primary, 1 = middle, 2 = secondary.
* Move-derived events (`onDrag`, `onDropTargetChange`) carry `-1`, as no button changed.
* Read `buttons` for what is held mid-drag.
*/
button: number;
/** `MouseEvent.buttons` bitmask. */
buttons: number;
/** Pointer X relative to the viewport, in CSS pixels. */
clientX: number;
/** Pointer Y relative to the viewport, in CSS pixels. */
clientY: number;
/** Pointer X relative to the document, in CSS pixels (includes scroll). */
pageX: number;
/** Pointer Y relative to the document, in CSS pixels (includes scroll). */
pageY: number;
/**
* The pointer device that produced this input, or `null` for a keyboard drag.
* Read the event's `mode` to detect a keyboard drag.
*/
pointerType: DragPointerType | null;
/** Whether the Control key was held. */
ctrlKey: boolean;
/** Whether the Shift key was held. */
shiftKey: boolean;
/** Whether the Alt key was held. */
altKey: boolean;
/** Whether the Meta (Command/Windows) key was held. */
metaKey: boolean;
};
```
### DragKind
A kind of draggable item or drop target, created with `Draggable.createKind` or
`Draggable.createGlobalKind`.
`TPayload` is the data things of this kind carry, so declaring it once on the kind
types `source.payload` and `self.payload` everywhere the kind is used.
```typescript
type DragKind = {
/**
* The name or global key used to create this kind. This is not an accessible
* name. Use `label` on a draggable or drop target instead.
*/
name: string;
/**
* The kind's runtime identity. `createKind` creates a fresh symbol for each call;
* `createGlobalKind` interns it on the namespaced key.
*/
id: symbol;
/** Whether this drag source is of this kind, narrowing its `payload` to `TPayload`. */
matches: matches;
};
```
### DragLocalPoint
Where the pointer sat inside a drop target, as a fraction of that target's border box:
`0` at the left/top edge, `1` at the right/bottom. See `DropTargetRecord.getLocalPoint`.
```typescript
type DragLocalPoint = { x: number; y: number };
```
### DragLocation
Snapshot of the pointer state and the active drop targets at one moment.
Each event carries its own snapshot, so it keeps reporting the moment it fired.
```typescript
type DragLocation = {
input: DragInput;
/** The active drop targets, innermost first. */
dropTargets: DropTargetRecord[];
};
```
### DragLocationHistory
The locations carried with every drag event.
```typescript
type DragLocationHistory = {
/** The location when the drag began. */
initial: DragLocation;
/** The location at the moment this event fires. */
current: DragLocation;
/**
* The location at the prior event. On the first event of a drag it holds the
* pickup input and no drop targets, so a `current` vs `previous` diff reads as
* no movement rather than a jump.
*/
previous: DragLocation;
};
```
### DragMode
The input method driving a drag.
- `'pointer'`: a mouse, pen, or touch gesture.
- `'keyboard'`: a keyboard gesture, whose coordinates are synthesized.
This event family covers Base UI registered draggable elements. Native
and external OS drags are outside it and would use a separate adapter and
event family rather than widening this union.
```typescript
type DragMode = 'pointer' | 'keyboard';
```
### DragMoveEventDetails
The event details passed to `onDrag`.
```typescript
type DragMoveEventDetails =
{ reason: 'pointer'; event: PointerEvent } | { reason: 'keyboard'; event: KeyboardEvent };
```
### DragSnappedLocalPointOptions
Options for `DropTargetRecord.getSnappedLocalPoint`.
```typescript
type DragSnappedLocalPointOptions = {
/**
* The point to snap. `'pointer'` uses the pointer position. `'source'` applies
* the grab offset first, so the result represents the dragged element's leading
* edges. Use `'source'` when committing the element's position. Falls back to
* `'pointer'` when no grab offset is available.
* @default 'pointer'
*/
anchor?: 'pointer' | 'source';
};
```
### DragSnapSteps
The number of equal steps used to snap a drop target's local point on each
axis. An omitted axis or non-positive count is not snapped. Counts divide the
target's border box and do not depend on its rendered size. For example,
`{ y: 96 }` divides a day column into 15-minute slots at any height.
```typescript
type DragSnapSteps = { x?: number; y?: number };
```
### DragSource
The drag source carried with every event.
Survives the original element being unmounted, for example by a virtualizer.
Every source in this event family is a registered Base UI draggable.
Native and external OS drags, which may have no source element, are outside
this contract and would use a separate adapter and event family.
```typescript
type DragSource = {
/** The draggable's own DOM element. */
element: HTMLElement;
/**
* Human-readable name supplied by the draggable's `label`, used by the default
* screen-reader announcements. `undefined` when the source was registered without one.
*/
label: string | undefined;
/**
* Identity of the kind supplied by the draggable's `kind`. Test it with the kind's
* `matches`, which narrows `payload` at the same time.
*/
kind: symbol;
/** The element the user pressed. `null` when the whole draggable is its own handle. */
dragHandle: Element | null;
/**
* Data supplied by the draggable's `payload`, evaluated at drag start.
* `undefined` when the source was registered without one.
*/
payload: TData;
};
```
### DragStartEventDetails
The event details passed to `onDragStart`.
```typescript
type DragStartEventDetails =
{ reason: 'pointer'; event: PointerEvent } | { reason: 'keyboard'; event: KeyboardEvent };
```
### DropEvent
The event object passed to a drop target's `onDrop`.
```typescript
type DropEvent = {
source: DragSource;
location: DragLocationHistory;
/**
* The input method driving the drag.
* This is the reliable way to detect a keyboard drag, as
* `location.current.input.pointerType` is `null` for those.
*/
mode: DragMode;
/** This drop target's own record. */
self: DropTargetRecord;
dropTarget: DropTargetRecord;
};
```
### DropTarget.anyKind
A catch-all kind for a drop target that accepts every drag on the page.
```tsx
```
The accepted source's payload is `unknown` until narrowed with a specific kind.
```typescript
type DropTargetanyKind = {
/**
* The name or global key used to create this kind. This is not an accessible
* name. Use `label` on a draggable or drop target instead.
*/
name: string;
/**
* The kind's runtime identity. `createKind` creates a fresh symbol for each call;
* `createGlobalKind` interns it on the namespaced key.
*/
id: symbol;
/** Whether this drag source is of this kind, narrowing its `payload` to `TPayload`. */
matches: matches;
};
```
### DropTargetChangeEvent
The event object passed to `onDropTargetChange`.
```typescript
type DropTargetChangeEvent = {
location: DragLocationHistory;
source: DragSource;
/**
* The input method driving the drag.
* This is the reliable way to detect a keyboard drag, as
* `location.current.input.pointerType` is `null` for those.
*/
mode: DragMode;
};
```
### DropTargetChangeEventDetails
The event details passed to `onDropTargetChange`, `onDragEnter` and `onDragLeave`.
```typescript
type DropTargetChangeEventDetails =
| { reason: 'pointer'; event: PointerEvent }
| { reason: 'keyboard'; event: KeyboardEvent }
| { reason: 'escape-key'; event: KeyboardEvent }
| { reason: 'tab-key'; event: KeyboardEvent }
| { reason: 'drop'; event: PointerEvent | KeyboardEvent }
| { reason: 'outside-release'; event: PointerEvent | KeyboardEvent }
| { reason: 'pointer-down'; event: PointerEvent }
| { reason: 'focus-out'; event: FocusEvent }
| { reason: 'imperative-action'; event: Event }
| { reason: 'window-blur'; event: FocusEvent }
| { reason: 'page-hidden'; event: Event }
| { reason: 'pointer-canceled'; event: PointerEvent }
| { reason: 'capture-lost'; event: PointerEvent }
| { reason: 'missed-release'; event: PointerEvent }
| { reason: 'document-detached'; event: Event }
| { reason: 'handler-error'; event: Event };
```
### DropTargetChangeReason
Why the hovered drop targets changed: an input moved the drag (`'pointer'` /
`'keyboard'`), or the drag ended and the targets are being released.
```typescript
type DropTargetChangeReason = DragMode | DragEndReason;
```
### DropTargetEvent
The event object passed to a drop target's event `K`.
Use it to type a handler extracted out of the JSX, which `DragEventMap` alone
would leave without `self`:
```ts
function handleDragEnter(event: DropTargetEvent<'onDragEnter', CardPayload, SlotData>) {}
```
```typescript
type DropTargetEvent<
K extends
| 'onDrag'
| 'onDragEnd'
| 'onDragEnter'
| 'onDragLeave'
| 'onDragStart'
| 'onDrop'
| 'onDropTargetChange',
TSourceData = unknown,
TLocalData = unknown,
> = {
location: DragLocationHistory;
source: DragSource;
/**
* The input method driving the drag.
* This is the reliable way to detect a keyboard drag, as
* `location.current.input.pointerType` is `null` for those.
*/
mode: DragMode;
/** This drop target's own record. */
self: DropTargetRecord;
};
```
### DropTargetPayload
A drop target's payload value.
```typescript
type DropTargetPayload = TLocalData;
```
### DropTargetRecord
A drop target in the active hover stack.
````typescript
type DropTargetRecord = {
/** The drop target's own DOM element. */
element: Element;
/**
* Human-readable name supplied by the drop target's `label`, used by the default
* screen-reader announcements. `undefined` when the target was registered without one.
*/
label: string | undefined;
/**
* Identity of the kind supplied by the drop target's `kind`, or `undefined` when the
* target was registered without one. Test it with the kind's `matches`, which narrows
* `payload` at the same time.
*/
kind: symbol | undefined;
/**
* Data supplied by the drop target's `payload`.
* `undefined` when the target was registered without one.
*/
payload: TLocalData;
/**
* Where the pointer sat inside this target when the target was resolved, as a fraction
* of the target's border box on each axis. Use it when the drop resolves to a value
* spread across the target rather than to the target itself:
*
* ```tsx
* {
* schedule(self.getLocalPoint().y * MINUTES_PER_DAY);
* }}
* />
* ```
*
* The first call measures the target. Later calls on the same record reuse the
* measurement. Records are rebuilt on every move.
*
* Not clamped: an ancestor in the stack can have the pointer outside its own box, so
* clamp where the domain requires it. Both axes report `0` for a target with no extent,
* including one detached since the drag began.
*/
getLocalPoint: () => DragLocalPoint;
/**
* Returns `getLocalPoint()` rounded to the target's `snap` steps and clamped
* between `0` and `1`:
*
* ```tsx
* {
* // Already a multiple of 15 minutes.
* schedule(source.payload.id, self.getSnappedLocalPoint().y * MINUTES_PER_DAY);
* }}
* />
* ```
*
* Pass `{ anchor: 'source' }` to snap the dragged element's leading edges instead
* of the pointer. An axis without declared steps returns its clamped raw fraction.
* This method shares the measurement from `getLocalPoint()`.
*/
getSnappedLocalPoint: (options?: DragSnappedLocalPointOptions) => DragLocalPoint;
};
````
### DropTargetResolutionContext
Context passed to a drop target's `canDrop` and `getPayload` callbacks.
```typescript
type DropTargetResolutionContext = {
/** Pointer state at the moment this callback runs. */
input: DragInput;
/** The drag source being evaluated against this target. */
source: DragSource;
/** This drop target's own DOM element. */
element: Element;
};
```
### DropTargetSelf
Extra fields included in the events of a drop target.
```typescript
type DropTargetSelf = {
/** This drop target's own record. */
self: DropTargetRecord;
};
```
## External Types
### matches
```typescript
type matches =
| ((source: {
element: HTMLElement;
label: string | undefined;
kind: symbol;
dragHandle: Element | null;
payload: unknown;
}) => boolean)
| ((target: {
element: Element;
label: string | undefined;
kind: symbol | undefined;
payload: unknown;
getLocalPoint: unknown;
getSnappedLocalPoint: unknown;
}) => boolean);
```
### DragPointerType
```typescript
type DragPointerType = 'mouse' | 'pen' | 'touch';
```
## Export Groups
- `DropTarget.Root`: `DropTarget.Root`, `DropTarget.Root.State`, `DropTarget.Root.Props`, `DropTarget.Root.PropsWithPayload`
- `DropTarget.createKind`
- `DropTarget.createGlobalKind`
- `Default`: `DropTarget.anyKind`, `BaseDragEvent`, `DragAccept`, `DragCanceledReason`, `DragCompletedReason`, `DragDropEvent`, `DragDropEventDetails`, `DragDropReason`, `DragEndReason`, `DragEventDetails`, `DragEventDetailsMap`, `DragEventMap`, `DragInput`, `DragKind`, `DragLocalPoint`, `DragLocation`, `DragLocationHistory`, `DragMode`, `DragMoveEventDetails`, `DragSnappedLocalPointOptions`, `DragSnapSteps`, `DragSource`, `DragStartEventDetails`, `DropEvent`, `DropTargetChangeEvent`, `DropTargetChangeEventDetails`, `DropTargetChangeReason`, `DropTargetEvent`, `DropTargetPayload`, `DropTargetPayloadGetter`, `DropTargetRecord`, `DropTargetResolutionContext`, `DropTargetSelf`, `DropTargetRootState`, `DropTargetRootProps`, `DropTargetRootPropsWithPayload`
## Canonical Types
Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.
- `DropTarget.Root.State`: `DropTargetRootState`
- `DropTarget.Root.Props`: `DropTargetRootProps`
- `DropTarget.Root.PropsWithPayload`: `DropTargetRootPropsWithPayload`
Alias of [`Draggable.createKind`](/react/components/draggable.md), provided on the `DropTarget` namespace so an integration that only renders targets does not need to import the draggable entry point.