Sensors - Dnd Kit — ContextQMD

Overview

Sensors detect user input and translate it into drag and drop operations. They handle the initiation, movement, and completion of drag operations from different input sources.

Built-in Sensors

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

<CardGroup cols={2}> <Card title="Pointer" icon="arrow-pointer" href="./sensors/pointer-sensor" > Handles mouse, touch, and pen input with configurable activation constraints. </Card> <Card title="Keyboard" icon="keyboard" href="./sensors/keyboard-sensor" > Enables keyboard navigation and activation using customizable key bindings. </Card> </CardGroup>

Usage

Sensors can be configured both globally and per draggable element. The sensors option accepts either an array or a function that receives the default sensors.

Extending defaults

Use the function form to configure or add sensors without replacing the defaults:

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

const manager = new DragDropManager({
  sensors: (defaults) => [
    ...defaults,
    PointerSensor.configure({
      activationConstraints: [
        new PointerActivationConstraints.Distance({value: 5}),
      ],
    }),
  ],
});

Replacing defaults

Pass an array to fully replace the default sensors:

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

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

Per-draggable sensors

Sensors can also be configured on individual draggable elements:

const draggable = new Draggable({
  id: 'draggable-1',
  element,
  sensors: [KeyboardSensor],
}, manager);

<Info> Local sensors configured on individual draggable elements take precedence over global sensors. </Info>

Creating Custom Sensors

You can create custom sensors by extending the Sensor class:

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

interface CustomSensorOptions {
  delay?: number;
}

class CustomSensor extends Sensor {
  constructor(manager, options?: CustomSensorOptions) {
    super(manager, options);
  }

  public bind(source) {
    // Register event listeners
    const unbind = this.registerEffect(() => {
      const target = source.handle ?? source.element;

      if (!target) return;

      const handleStart = (event) => {
        if (this.disabled) return;

        this.manager.actions.setDragSource(source.id);
        this.manager.actions.start({
          event,
          coordinates: getCoordinates(event)
        });
      };

      target.addEventListener('customstart', handleStart);

      return () => {
        target.removeEventListener('customstart', handleStart);
      };
    });

    return unbind;
  }
}

Sensor Lifecycle

Construction
- Sensor instance created
- Options configured
- Initial setup performed
Binding
- Sensor bound to draggable element
- Event listeners registered
- Effects set up
Operation
- Input detected
- Coordinates tracked
- Drag operations managed
Cleanup
- Event listeners removed
- Effects cleaned up
- Resources released

API Reference

Base Sensor Class

<ParamField path="manager" type="DragDropManager" required> Reference to the drag and drop manager instance. </ParamField> <ParamField path="options" type="SensorOptions"> Optional configuration options for the sensor. </ParamField>

Methods

bind(source: Draggable): Bind sensor to draggable element
enable(): Enable the sensor
disable(): Disable the sensor
isDisabled(): Check if sensor is disabled
destroy(): Clean up sensor resources

Static Methods

configure(options): Create a configured sensor descriptor

const configuredSensor = CustomSensor.configure({
  delay: 500
});

const manager = new DragDropManager({
  sensors: [configuredSensor]
});