🌜
🌞
@dnd-kit/modifiers

@dnd-kit/modifiers

v6.0.0

Translate modifier presets for use with `@dnd-kit` packages.

npm install @dnd-kit/modifiers

README

@dnd-kit/modifiers

Stable release

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,
  };
}

General

License
MIT
Typescript Types
None found
Tree-shakeable
Yes

Popularity

GitHub Stargazers
5,433
Community Interest
3,252
Number of Forks
282

Maintenance

Commits
10/219/22050
Last Commit
Open Issues
134
Closed Issues
370
Open Pull Requests
16
Closed Pull Requests
37

Versions

Versions Released
10/219/22020
Latest Version Released
May 21, 2022
Current Tags
latest6.0.0
next6.0.0-next-202242114536

Dependencies

Dependencies (2)
Dev Dependencies (1)

Contributors

clauderic
clauderic
Commits: 178
github-actions[bot]
github-actions[bot]
Commits: 26
ranbena
ranbena
Commits: 5
wmain
wmain
Commits: 2
medihack
medihack
Commits: 2
emma-boardman
emma-boardman
Commits: 1
chestozo
chestozo
Commits: 1
mitchheddles
mitchheddles
Commits: 1
trentmwillis
trentmwillis
Commits: 1
supersebh
supersebh
Commits: 1
lsit
lsit
Commits: 1
Pustelto
Pustelto
Commits: 1
akhmadullin
akhmadullin
Commits: 1
inokawa
inokawa
Commits: 1
py-wai
py-wai
Commits: 1