dnd-kit Documentation

File: apps/stories/stories/react/Draggable/DragHandles/docs/DragHandles.mdx Copy Chapter

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

import {Info, Preview} from '../../../../components';
import {DragHandle} from '../DragHandles.stories.tsx';

Drag handles

Restrict dragging to a specific element within a draggable element.

Usage Copy Chapter

To create a drag handle, provide a handle element to the useDraggable hook by consuming the handleRef from the output object of the useDraggable hook.

import {useDraggable} from '@dnd-kit/react';

function Draggable(props) {
  const {handleRef, ref} = useDraggable({
    id: props.id,
  });

  return (
    
      {props.children}
      Drag handle
    
  );
}

Alternatively, you can also pass an Element or ref to an element as an argument to the handle option of useDraggable:

import {useDraggable} from '@dnd-kit/react';

function Draggable(props) {
  const handleRef = useRef(null);
  const {ref} = useDraggable({
    id: props.id,
    handle: handleRef,
  });

  return (
    
      {props.children}
      Drag handle
    
  );
}

File: apps/stories/stories/react/Draggable/Modifiers/docs/ModifierDocs.mdx Copy Chapter

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

import {Info, Preview} from '../../../../components';
import {DraggableExample} from '../../DraggableExample';

Modifiers

Modify or restrict the behavior of draggable elements.

<DraggableExample
modifiers={[
RestrictToElement.configure({
element() {
return document.getElementById('modifier-hero');
},
}),
]}
/>

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

Usage Copy Chapter

Modifiers can be applied globally or to individual draggable elements.

Global modifiers Copy Section

Modifiers can be applied globally by passing them to the <DragDropProvider> component.

import {DragDropProvider} from '@dnd-kit/react';
import {RestrictToVerticalAxis} from '@dnd-kit/abstract/modifiers';
import {RestrictToWindow} from '@dnd-kit/dom/modifiers';

function App() {
  return (
    <DragDropProvider modifiers={[RestrictToWindow, RestrictToVerticalAxis]}>
      {...}
    </DragDropProvider>
  )
}

Local modifiers Copy Section

Local modifiers take precedence over global modifiers.

Modifiers can also be applied to individual draggable elements by passing them to the modifiers prop.

import {useDraggable} from '@dnd-kit/react';
import {RestrictToVerticalAxis} from '@dnd-kit/abstract/modifiers';
import {RestrictToWindow} from '@dnd-kit/dom/modifiers';

function Draggable({id}) {
  const {ref} = useDraggable({
    id,
    modifiers: [RestrictToVerticalAxis, RestrictToWindow],
  });
}

File: apps/stories/stories/react/Draggable/Sensors/docs/SensorDocs.mdx Copy Chapter

import {Info, Preview} from '../../../../components';
import {DraggableExample} from '../../DraggableExample';

Sensors

Detect user input and translate them into drag operations.

Overview Copy Chapter

Sensors are an abstraction to detect different input methods in order to initiate drag operations, respond to movement and end or cancel the operation.

Built-in sensors Copy Chapter

The @dnd-kit/dom package provides built-in sensors that can be used to detect user input in the browser.

Pointer sensor Copy Section

The Pointer sensor responds to Pointer events. This sensor is enabled by default.

Pointer events are DOM events that are fired for a pointing device. They are designed to create a single DOM event model to handle pointing input devices such as a mouse, pen/stylus or touch (such as one or more fingers).
The pointer is a hardware-agnostic device that can target a specific set of screen coordinates.

– Source: MDN

Activation constraints

The Pointer sensor has two types of activation constraints:

• Distance constraint
• Delay constraint

These activation constraints are not mutually exclusive, they can be used simultaneously. In case both constraints are used, the Pointer sensor will activate as soon as one of the constraints is met.

import {PointerSensor, PointerActivationConstraints} from '@dnd-kit/dom';

const sensors = [
  PointerSensor.configure({
    activationConstraints: [
      new PointerActivationConstraints.Delay({value: 200, tolerance: 10}),
      new PointerActivationConstraints.Distance({value: 5}),
    ],
  }),
];

The distance value property represents the distance, in pixels, that a pointer needs to be moved by before a drag operation is initiated.

The delay value property represents the duration, in milliseconds, that a draggable item needs to be held by the primary pointer for before a drag start event is emitted.

The tolerance property represents the distance, in pixels, of motion that is tolerated before the drag operation is aborted. If the pointer is moved during the delay duration and the tolerance is set to zero, the drag operation will be immediately aborted. If a higher tolerance is set, for example, a tolerance of 5 pixels, the operation will only be aborted if the pointer is moved by more than 5 pixels during the delay.

This property is particularly useful for touch input, where some tolerance should be accounted for when using a delay constraint, as touch input is less precise than mouse input.

Default behavior

By default, the PointerSensor applies sensible activation constraints depending on the context:

• Mouse on handle: activates immediately.
• Touch: Delay({value: 250, tolerance: 5}).
• Text inputs: Delay({value: 200, tolerance: 0}).
• Other cases: Delay({value: 200, tolerance: 10}) and Distance({value: 5}).

You can override this with activationConstraints, which may be an array of constraints or a function (event, source) => ActivationConstraints | undefined to compute them per interaction.

import {PointerSensor, PointerActivationConstraints} from '@dnd-kit/dom';

PointerSensor.configure({
  activationConstraints(event, source) {
    if (event.pointerType === 'touch') {
      return [
        new PointerActivationConstraints.Delay({value: 300, tolerance: 8}),
      ];
    }
    return [new PointerActivationConstraints.Distance({value: 6})];
  },
});

Activator elements

You may specify additional elements that can start a pointer interaction via activatorElements:

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

PointerSensor.configure({
  activatorElements(source) {
    return [
      source.handle,
      document.querySelector('[data-dnd-activator]'),
    ];
  },
});

Keyboard sensor Copy Section

The Keyboard sensor responds to Keyboard events. This sensor is enabled by default.

The keyboard sensor activates when the handle or element of a draggable source is focused and the Space or Enter key is pressed.

Configuration

The Keyboard sensor can be configured to respond to different keyboard keys:

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

const sensors = [
  KeyboardSensor.configure({
    keyboardCodes: {
      start: ['Space', 'Enter'],
      cancel: ['Escape'],
      end: ['Space', 'Enter'],
      up: ['ArrowUp'],
      down: ['ArrowDown'],
      left: ['ArrowLeft'],
      right: ['ArrowRight'],
    },
  }),
];

Keyboard sensor bindings use KeyboardEvent.key values such as w, Enter, and ArrowUp. Common legacy Key* and Digit* code values normalize for compatibility, but physical key codes such as NumpadEnter should be replaced with the key value they produce. Other named keys must match KeyboardEvent.key casing.

You may customize these values, but do keep in mind that the third rule of ARIA requires that a user must be able to activate the action associated with a draggable widget using both the enter (on Windows) or return (on macOS) and the space key. To learn more, read the in-depth accessibility guide.

Usage Copy Chapter

Sensors can be applied globally or to individual draggable elements.

Global sensors Copy Section

Sensors can be applied globally by passing them to the <DragDropProvider> component.

import {DragDropProvider} from '@dnd-kit/react';
import {PointerSensor, KeyboardSensor} from '@dnd-kit/dom';

function App() {
  return (
    <DragDropProvider sensors={[PointerSensor, KeyboardSensor]}>
      {...}
    </DragDropProvider>
  )
}

Local sensors Copy Section

Local sensors take precedence over global sensors.

Sensors can also be applied to individual draggable elements by passing them to the sensors prop.

import {useDraggable} from '@dnd-kit/react';
import {KeyboardSensor} from '@dnd-kit/dom';

function Draggable({id}) {
  const {ref} = useDraggable({
    id,
    sensors: [KeyboardSensor],
  });
}

2. Official Technical Reference & Guides (clauderic/docs) Copy Chapter

Mintlify Starter Kit

Click on Use this template to copy the Mintlify starter kit. The starter kit contains examples including

• Guide pages
• Navigation
• Customizations
• API Reference pages
• Use of popular components

Development Copy Section

Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command

npm i mintlify

Run the following command at the root of your documentation (where mint.json is)

mintlify dev

Publishing Changes Copy Section

Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.

Troubleshooting

• Mintlify dev isn't running - Run mintlify install it'll re-install dependencies.
• Page loads as a 404 - Make sure you are running in a folder with mint.json