Modifiers - Dnd Kit — ContextQMD

Overview

Modifiers transform the movement of draggable elements during drag operations. They can restrict movement to axes or boundaries, adjust positioning, or implement any custom movement logic.

Built-in Modifiers

Abstract Modifiers

Available in @dnd-kit/abstract/modifiers, these modifiers are environment-agnostic:

<CardGroup cols={2}> <Card title="RestrictToHorizontalAxis"> Constrain movement to the horizontal axis only </Card> <Card title="RestrictToVerticalAxis"> Constrain movement to the vertical axis only </Card> <Card title="Snap"> Snap movement to a grid with configurable size </Card> </CardGroup>

Example using axis restriction:

import {RestrictToVerticalAxis} from '@dnd-kit/abstract/modifiers';

// Only allow vertical movement
const manager = new DragDropManager({
  modifiers: [RestrictToVerticalAxis],
});

Example combining 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)
      }
    })
  ],
});

<Info> Modifiers are applied in order, so place restrictions before transformations. </Info>

Concrete Modifiers

Environment-specific modifiers for the DOM, available in @dnd-kit/dom/modifiers:

<CardGroup cols={2}> <Card title="RestrictToWindow"> Constrain movement within the window boundaries </Card> <Card title="RestrictToElement"> Constrain movement within a container element </Card> </CardGroup>

Usage

Modifiers can be applied globally or per draggable element. The modifiers option accepts either an array or a function that receives the default modifiers.

Extending defaults

Use the function form to add modifiers without replacing the defaults:

import {DragDropManager} from '@dnd-kit/dom';
import {RestrictToWindow} from '@dnd-kit/dom/modifiers';

const manager = new DragDropManager({
  modifiers: (defaults) => [...defaults, RestrictToWindow],
});

Replacing defaults

Pass an array to fully replace the default modifiers:

import {DragDropManager} from '@dnd-kit/dom';
import {RestrictToWindow} from '@dnd-kit/dom/modifiers';

const manager = new DragDropManager({
  modifiers: [RestrictToWindow],
});

Per-draggable modifiers

Modifiers can also be configured on individual draggable elements:

import {RestrictToElement} from '@dnd-kit/dom/modifiers';

const draggable = new Draggable({
  id: 'draggable-1',
  element,
  modifiers: [
    RestrictToElement.configure({
      element: containerElement
    })
  ],
}, manager);

<Info> Local modifiers on draggable elements take precedence over global modifiers. </Info>

Creating Custom Modifiers

Create custom modifiers by extending the Modifier class:

import {Modifier} from '@dnd-kit/abstract';
import type {Coordinates} from '@dnd-kit/geometry';

interface GridOptions {
  gridSize: number;
}

class SnapToGrid extends Modifier {
  constructor(manager, options?: GridOptions) {
    super(manager, options);
  }

  public apply(operation): Coordinates {
    if (this.disabled) return operation.transform;

    const {gridSize = 20} = this.options ?? {};
    const {transform} = operation;

    return {
      x: Math.round(transform.x / gridSize) * gridSize,
      y: Math.round(transform.y / gridSize) * gridSize,
    };
  }
}

Modifier Lifecycle

Construction
- Modifier instance created
- Options configured
Application
- apply() called during drag
- Transforms coordinates
- Can access drag operation state
Cleanup
- Resources cleaned up on destroy

API Reference

Base Modifier Class

<ParamField path="manager" type="DragDropManager" required> Reference to the drag and drop manager instance. </ParamField> <ParamField path="options" type="Record<string, any>"> Optional configuration for the modifier. </ParamField>

Methods

apply(operation): Transform drag coordinates
enable(): Enable the modifier
disable(): Disable the modifier
isDisabled(): Check if modifier is disabled
destroy(): Clean up resources

Static Methods

configure(options): Create configured modifier

const snapToGrid = SnapToGrid.configure({
  gridSize: 10
});

const manager = new DragDropManager({
  modifiers: [snapToGrid]
});