dnd kit

Sensors

Sensors

Detect user input and translate it into drag and drop operations.

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:

Pointer

Handles mouse, touch, and pen input with configurable activation constraints.

Keyboard

Enables keyboard navigation and activation using customizable key bindings.

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);

Local sensors configured on individual draggable elements take precedence over global sensors.

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

  1. Construction

    • Sensor instance created
    • Options configured
    • Initial setup performed

  2. Binding

    • Sensor bound to draggable element
    • Event listeners registered
    • Effects set up

  3. Operation

    • Input detected
    • Coordinates tracked
    • Drag operations managed

  4. Cleanup

    • Event listeners removed
    • Effects cleaned up
    • Resources released

API Reference

Base Sensor Class

manager
DragDropManager
required

Reference to the drag and drop manager instance.

options
SensorOptions

Optional configuration options for the sensor.

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]
});