Marc Mintel
5397309103
Some checks failed
Build & Deploy / 🔍 Prepare (push) Successful in 20s
Build & Deploy / 🧪 QA (push) Failing after 34s
Build & Deploy / 🏗️ Build (push) Has started running
Build & Deploy / 🚀 Deploy (push) Has been cancelled
Build & Deploy / 🧪 Smoke Test (push) Has been cancelled
Build & Deploy / ⚡ Lighthouse (push) Has been cancelled
Build & Deploy / 🔔 Notify (push) Has been cancelled
107 lines
2.8 KiB
Plaintext
107 lines
2.8 KiB
Plaintext
# @dnd-kit/modifiers
|
|
|
|
[](https://npm.im/@dnd-kit/sortable)
|
|
|
|
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`.
|
|
|
|
```jsx
|
|
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.
|
|
|
|
```javascript
|
|
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:
|
|
|
|
```javascript
|
|
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,
|
|
};
|
|
}
|
|
```
|