@dnd-kit/modifiers

What is @dnd-kit/modifiers?

@dnd-kit/modifiers is a package that provides a set of utilities to modify the behavior of drag-and-drop interactions in the @dnd-kit library. It allows you to constrain, restrict, and customize the dragging experience in various ways.

What are @dnd-kit/modifiers's main functionalities?

Restrict Movement

This feature allows you to restrict the movement of draggable items to the horizontal axis only. By using the `restrictToHorizontalAxis` modifier, you can ensure that items can only be dragged left or right.

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

const modifiers = [restrictToHorizontalAxis];

<DndContext modifiers={modifiers}>
  {/* Your draggable components here */}
</DndContext>;

Restrict to Parent Bounds

This feature restricts the movement of draggable items to the bounds of their parent element. The `restrictToParentElement` modifier ensures that items cannot be dragged outside their parent container.

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

const modifiers = [restrictToParentElement];

<DndContext modifiers={modifiers}>
  {/* Your draggable components here */}
</DndContext>;

Snap to Grid

This feature allows you to snap draggable items to a grid. By using the `snapToGrid` modifier with specified grid dimensions, you can ensure that items snap to the nearest grid point when dragged.

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

const modifiers = [snapToGrid({ x: 20, y: 20 })];

<DndContext modifiers={modifiers}>
  {/* Your draggable components here */}
</DndContext>;

Other packages similar to @dnd-kit/modifiers

react-dnd

react-dnd is a popular library for drag-and-drop interactions in React. It provides a flexible and customizable API for implementing drag-and-drop functionality. While it does not have built-in modifiers like @dnd-kit/modifiers, it offers a wide range of customization options through its API.

react-beautiful-dnd

react-beautiful-dnd is another popular drag-and-drop library for React. It focuses on providing a beautiful and accessible drag-and-drop experience. Similar to react-dnd, it does not have built-in modifiers but offers a high level of customization through its API.

react-draggable

react-draggable is a library for making elements draggable in React. It provides basic drag-and-drop functionality and allows for customization through props. While it does not offer the same level of customization as @dnd-kit/modifiers, it is a lightweight alternative for simple drag-and-drop use cases.

README

@dnd-kit/modifiers

Modifiers let you dynamically modify the movement coordinates that are detected by sensors. They can be used for a wide range of use cases, for example:

• Restricting motion to a single axis
• Restricting motion to the draggable node container's bounding rectangle
• Restricting motion to the draggable node's scroll container bounding rectangle
• Applying resistance or clamping the motion

Installation

To start using modifiers, install the modifiers package via yarn or npm:

npm install @dnd-kit/modifiers

Usage

The modifiers repository contains a number of useful modifiers that can be applied on DndContext as well as DragOverlay.

import {DndContext, DragOverlay} from '@dnd-kit';
import {
  restrictToVerticalAxis,
  restrictToWindowEdges,
} from '@dnd-kit/modifiers';

function App() {
  return (
    <DndContext modifiers={[restrictToVerticalAxis]}>
      {/* ... */}
      <DragOverlay modifiers={[restrictToWindowEdges]}>{/* ... */}</DragOverlay>
    </DndContext>
  );
}

As you can see from the example above, DndContext and DragOverlay can both have different modifiers.

Built-in modifiers

Restricting motion to an axis

restrictToHorizontalAxis

Restrict movement to only the horizontal axis.

restrictToVerticalAxis

Restrict movement to only the vertical axis.

Restrict motion to a container's bounding rectangle

restrictToWindowEdges

Restrict movement to the edges of the window. This modifier can be useful to prevent the DragOverlay from being moved outside of the bounds of the window.

restrictToParentElement

Restrict movement to the parent element of the draggable item that is picked up.

restrictToFirstScrollableAncestor

Restrict movement to the first scrollable ancestor of the draggable item that is picked up.

Snap to grid

createSnapModifier

Function to create modifiers to snap to a given grid size.

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

const gridSize = 20; // pixels
const snapToGridModifier = createSnapModifier(gridSize);

Snap to cursor

snapCenterToCursor

Snaps the center of the draggable item to the cursor when it is picked up. Has no effect when using the Keyboard sensor.

Building custom modifiers

To build your own custom modifiers, refer to the implementation of the built-in modifiers of this package.

For example, here is an implementation to create a modifier to snap to grid:

const gridSize = 20;

function snapToGrid(args) {
  const {transform} = args;

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