[experimental] Add SnapToPointer modifier

.changeset/add-snap-center-to-cursor-modifier.md

@@ -0,0 +1,5 @@
+---
+'@dnd-kit/dom': patch
+---
+
+Added `SnapToPointer` modifier that offsets the drag transform so a specified anchor point of the dragged element snaps to the cursor position. The `anchor` option accepts an `{x, y}` object with values between `0` and `1` representing the relative position within the draggable element. Defaults to `{x: 0.5, y: 0.5}` (center).

apps/docs/extend/modifiers.mdx

@@ -21,7 +21,7 @@ Available in `@dnd-kit/abstract/modifiers`, these modifiers are environment-agno
   <Card title="RestrictToVerticalAxis">
     Constrain movement to the vertical axis only
   </Card>
-  <Card title="Snap">
+  <Card title="SnapToPointer">
     Snap movement to a grid with configurable size
   </Card>
 </CardGroup>
@@ -40,21 +40,18 @@ const manager = new DragDropManager({
 Example combining modifiers:
 
 ```ts
-import {
-  Snap,
-  RestrictToHorizontalAxis
-} from '@dnd-kit/abstract/modifiers';
+import {Snap, RestrictToHorizontalAxis} from '@dnd-kit/abstract/modifiers';
 
 // Horizontal movement that snaps to a grid
 const manager = new DragDropManager({
   modifiers: [
     RestrictToHorizontalAxis,
     Snap.configure({
       size: {
-        x: 20,  // Snap every 20px horizontally
-        y: 0    // No vertical snapping (already restricted)
-      }
-    })
+        x: 20, // Snap every 20px horizontally
+        y: 0, // No vertical snapping (already restricted)
+      },
+    }),
   ],
 });
 ```
@@ -74,6 +71,10 @@ Environment-specific modifiers for the DOM, available in `@dnd-kit/dom/modifiers
   <Card title="RestrictToElement">
     Constrain movement within a container element
   </Card>
+  <Card title="SnapToPointer">
+    Offset the drag transform so a specified anchor point of the element snaps
+    to the cursor position
+  </Card>
 </CardGroup>
 
 ## Usage
@@ -82,28 +83,50 @@ Modifiers can be applied globally or per draggable element:
 
 ```ts
 import {DragDropManager} from '@dnd-kit/dom';
-import {
-  RestrictToWindow,
-  RestrictToElement
-} from '@dnd-kit/dom/modifiers';
+import {RestrictToWindow, RestrictToElement} from '@dnd-kit/dom/modifiers';
 
 // Global modifiers
 const manager = new DragDropManager({
-  modifiers: [
-    RestrictToWindow,
-  ],
+  modifiers: [RestrictToWindow],
 });
 
 // Per-draggable modifiers
-const draggable = new Draggable({
-  id: 'draggable-1',
-  element,
-  modifiers: [
-    RestrictToElement.configure({
-      element: containerElement
-    })
-  ],
-}, manager);
+const draggable = new Draggable(
+  {
+    id: 'draggable-1',
+    element,
+    modifiers: [
+      RestrictToElement.configure({
+        element: containerElement,
+      }),
+    ],
+  },
+  manager
+);
+```
+
+### SnapToPointer
+
+When dragging starts, `SnapToPointer` immediately repositions the element so the specified anchor point aligns with the cursor. The `anchor` option accepts an `{x, y}` object with values between `0` and `1` representing the relative position within the draggable element. Defaults to `{x: 0.5, y: 0.5}` (center).
+
+```ts
+import {DragDropManager} from '@dnd-kit/dom';
+import {SnapToPointer} from '@dnd-kit/dom/modifiers';
+
+// Default: snap center to cursor
+const manager = new DragDropManager({
+  modifiers: [SnapToPointer],
+});
+
+// Snap top-left corner to cursor
+const manager = new DragDropManager({
+  modifiers: [SnapToPointer.configure({anchor: {x: 0, y: 0}})],
+});
+
+// Snap bottom-right corner to cursor
+const manager = new DragDropManager({
+  modifiers: [SnapToPointer.configure({anchor: {x: 1, y: 1}})],
+});
 ```
 
 <Info>
@@ -181,10 +204,10 @@ class SnapToGrid extends Modifier {
 
 ```ts
 const snapToGrid = SnapToGrid.configure({
-  gridSize: 10
+  gridSize: 10,
 });
 
 const manager = new DragDropManager({
-  modifiers: [snapToGrid]
+  modifiers: [snapToGrid],
 });
 ```

apps/stories/stories/react/Draggable/Modifiers/Modifiers.stories.tsx

@@ -3,7 +3,11 @@ import {
   RestrictToHorizontalAxis,
   RestrictToVerticalAxis,
 } from '@dnd-kit/abstract/modifiers';
-import {RestrictToElement, RestrictToWindow} from '@dnd-kit/dom/modifiers';
+import {
+  RestrictToElement,
+  RestrictToWindow,
+  SnapToPointer,
+} from '@dnd-kit/dom/modifiers';
 
 import docs from './docs/ModifierDocs.mdx';
 import {DraggableExample} from '../DraggableExample';
@@ -69,3 +73,10 @@ export const SnapModifierExample: Story = {
   name: 'Snap to grid',
   render: SnapToGridExample,
 };
+
+export const SnapToPointerModifier: Story = {
+  name: 'Snap to pointer',
+  args: {
+    modifiers: [SnapToPointer],
+  },
+};

apps/stories/stories/react/Draggable/Modifiers/docs/ModifierDocs.mdx

@@ -1,4 +1,4 @@
-import {RestrictToElement} from '@dnd-kit/dom/modifiers';
+import {RestrictToElement, SnapToPointer} from '@dnd-kit/dom/modifiers';
 
 import {Info, Preview} from '../../../../components';
 import {DraggableExample} from '../../DraggableExample';
@@ -26,6 +26,44 @@ Modifiers let you dynamically modify the movement coordinates that are detected
 - Restricting motion to the draggable node's scroll container bounding rectangle
 - Applying resistance or clamping the motion
 
+## Built-in modifiers
+
+### `@dnd-kit/abstract/modifiers`
+
+| Modifier                   | Description                                    |
+| -------------------------- | ---------------------------------------------- |
+| `RestrictToVerticalAxis`   | Restricts drag movement to the vertical axis   |
+| `RestrictToHorizontalAxis` | Restricts drag movement to the horizontal axis |
+| `SnapModifier`             | Snaps drag movement to a grid                  |
+
+### `@dnd-kit/dom/modifiers`
+
+| Modifier            | Description                                                                                        |
+| ------------------- | -------------------------------------------------------------------------------------------------- |
+| `RestrictToWindow`  | Restricts the draggable element to stay within the viewport                                        |
+| `RestrictToElement` | Restricts the draggable element to stay within a given element                                     |
+| `SnapToPointer`     | Offsets the drag transform so a specified anchor point of the element snaps to the cursor position |
+
+#### `SnapToPointer`
+
+When dragging starts, `SnapToPointer` immediately repositions the element so the specified anchor point aligns with the cursor. The `anchor` option accepts an `{x, y}` object with values between `0` and `1` representing the relative position within the draggable element. Defaults to `{x: 0.5, y: 0.5}` (center).
+
+<Preview>
+  <DraggableExample modifiers={[SnapToPointer]} />
+</Preview>
+
+```jsx
+import {useDraggable} from '@dnd-kit/react';
+import {SnapToPointer} from '@dnd-kit/dom/modifiers';
+
+function Draggable({id}) {
+  const {ref} = useDraggable({
+    id,
+    modifiers: [SnapToPointer],
+  });
+}
+```
+
 ## Usage
 
 Modifiers can be applied globally or to individual draggable elements.

packages/abstract/src/core/plugins/plugin.ts

@@ -93,7 +93,7 @@ export abstract class Plugin<
    * @param callback - The effect callback to register
    * @returns A function to dispose of the effect
    */
-  protected registerEffect(callback: () => void) {
+  protected registerEffect(callback: () => void): CleanupFunction {
     const dispose = effect(callback.bind(this));
 
     this.#cleanupFunctions.add(dispose);

packages/dom/src/core/sensors/keyboard/KeyboardSensor.ts

@@ -88,7 +88,7 @@ export class KeyboardSensor extends Sensor<
 
   protected listeners = new Listeners();
 
-  public bind(source: Draggable, options = this.options) {
+  public bind(source: Draggable, options = this.options): CleanupFunction {
     const unbind = effect(() => {
       const target = source.handle ?? source.element;
       const listener: EventListener = (event: Event) => {

packages/dom/src/core/sensors/pointer/PointerSensor.ts

@@ -130,7 +130,7 @@ export class PointerSensor extends Sensor<
     return constraints;
   }
 
-  public bind(source: Draggable, options = this.options) {
+  public bind(source: Draggable, options = this.options): CleanupFunction {
     const unbind = effect(() => {
       const controller = new AbortController();
       const {signal} = controller;

packages/dom/src/modifiers/SnapToPointer.ts

@@ -0,0 +1,35 @@
+import {Modifier, configurator} from '@dnd-kit/abstract';
+import type {DragOperation} from '@dnd-kit/abstract';
+import type {DragDropManager} from '@dnd-kit/dom';
+
+interface Anchor {
+  x: number;
+  y: number;
+}
+
+interface Options {
+  anchor?: Anchor;
+}
+
+const DEFAULT_ANCHOR: Anchor = {x: 0.5, y: 0.5};
+
+export class SnapToPointer extends Modifier<DragDropManager, Options> {
+  apply({activatorEvent, shape, transform}: DragOperation) {
+    if (!shape || !(activatorEvent instanceof PointerEvent)) {
+      return transform;
+    }
+
+    const anchor = this.options?.anchor ?? DEFAULT_ANCHOR;
+    const {boundingRectangle} = shape.initial;
+
+    const anchorX = boundingRectangle.left + boundingRectangle.width * anchor.x;
+    const anchorY = boundingRectangle.top + boundingRectangle.height * anchor.y;
+
+    return {
+      x: transform.x + activatorEvent.clientX - anchorX,
+      y: transform.y + activatorEvent.clientY - anchorY,
+    };
+  }
+
+  static configure = configurator(SnapToPointer);
+}

packages/dom/src/modifiers/index.ts

@@ -1,2 +1,3 @@
 export {RestrictToWindow} from './RestrictToWindow.ts';
 export {RestrictToElement} from './RestrictToElement.ts';
+export {SnapToPointer} from './SnapToPointer.ts';