Sensors

Input handlers for detecting and initiating drag operations

Sensor is the abstract base class for all sensor implementations in dnd-kit. Sensors are responsible for detecting and initiating drag operations by handling user interactions such as mouse, touch, keyboard, or custom input methods.

Sensor Class

Constructor

Creates a new sensor instance.

class MySensor extends Sensor<T, U> {
  constructor(manager: T, options?: U) {
    super(manager, options);
  }
}

manager · T extends DragDropManager · required

The drag and drop manager instance.

options · U extends SensorOptions

Optional sensor configuration.

T · extends DragDropManager<any, any> · default: "DragDropManager<Draggable, Droppable>"

Type parameter for the drag drop manager.

U · extends SensorOptions · default: "SensorOptions"

Type parameter for sensor options.

Properties

manager

manager · T

The drag drop manager instance that this sensor is bound to.

const manager = sensor.manager;

options

options · U | undefined

The configuration options for this sensor instance.

const options = sensor.options;

disabled

disabled · boolean

Whether the sensor instance is disabled.

sensor.disabled = true;

Inherited from Plugin.

Methods

bind() (abstract)

Binds the sensor to a draggable source. Must be implemented by subclasses.

public abstract bind(source: Draggable, options?: U): CleanupFunction;

source · Draggable · required

The draggable element to bind to.

options · U

Optional sensor options specific to this draggable.

return · CleanupFunction

A cleanup function that unbinds the sensor when called.

type CleanupFunction = () => void;

Inherited from Plugin

enable()

Enables a disabled sensor instance.

sensor.enable();

disable()

Disables an enabled sensor instance.

sensor.disable();

isDisabled()

Checks if the sensor instance is disabled.

const disabled = sensor.isDisabled();

return · boolean

true if the sensor is disabled.

configure()

Configures a sensor instance with new options.

sensor.configure({option: 'value'});

options · U

The new options to apply.

destroy()

Destroys a sensor instance and cleans up its resources.

sensor.destroy();

Static Methods

configure()

Configures a sensor constructor with default options.

const ConfiguredSensor = MySensor.configure({
  activationDistance: 10,
  activationDelay: 200
});

options · PluginOptions · required

The options to configure the constructor with.

return · SensorDescriptor

A configured sensor descriptor that can be passed to the manager.

Types

SensorOptions

Base type for sensor options.

type SensorOptions = PluginOptions;
type PluginOptions = Record<string, any>;

SensorConstructor

Constructor type for creating sensor instances.

type SensorConstructor<T extends DragDropManager<any, any>> = 
  PluginConstructor<T, Sensor<T>>;

interface PluginConstructor<T, U> {
  new (manager: T, options?: PluginOptions): U;
}

SensorDescriptor

Descriptor type for configuring sensors.

type SensorDescriptor<T extends DragDropManager<any, any>> = 
  PluginDescriptor<T, Sensor<T>, SensorConstructor<T>>;

type PluginDescriptor<T, U, V> = {
  plugin: V;
  options?: PluginOptions;
};

Sensors

Array type for multiple sensor configurations.

type Sensors<T extends DragDropManager<any, any>> = 
  (SensorConstructor<T> | SensorDescriptor<T>)[];

Activation Constraints

ActivationConstraint

Abstract base class for activation constraints.

abstract class ActivationConstraint<E extends Event, O extends ActivationConstraintOptions> {
  constructor(protected options: O);
  
  abstract onEvent(event: E): void;
  abstract abort(event?: E): void;
  
  protected activate(event: E): void;
}

Activation constraints allow you to control when a drag operation should start based on specific conditions.

ActivationController

Controller for managing activation constraints.

class ActivationController<E extends Event> extends AbortController {
  public activated: boolean;
  
  constructor(
    constraints: ActivationConstraints<E> | undefined,
    onActivate: (event: E) => void
  );
  
  onEvent(event: E): void;
  activate(event: E): void;
  abort(event?: E): void;
}

ActivationConstraints

Array type for activation constraints.

type ActivationConstraints<E extends Event> = ActivationConstraint<E>[];

Implementing a Custom Sensor

Basic Implementation

import {Sensor, type SensorOptions} from '@dnd-kit/abstract';
import type {Draggable} from '@dnd-kit/abstract';

interface MySensorOptions extends SensorOptions {
  threshold?: number;
}

class MySensor extends Sensor<DragDropManager, MySensorOptions> {
  constructor(manager: DragDropManager, options?: MySensorOptions) {
    super(manager, options);
  }

  public bind(source: Draggable, options?: MySensorOptions): CleanupFunction {
    const threshold = options?.threshold ?? this.options?.threshold ?? 5;
    
    const handleStart = (event: PointerEvent) => {
      if (this.isDisabled()) return;
      
      const controller = this.manager.actions.start({
        source,
        event,
        coordinates: {x: event.clientX, y: event.clientY}
      });
      
      // Handle move, end events...
    };
    
    // Attach event listeners
    source.element?.addEventListener('pointerdown', handleStart);
    
    // Return cleanup function
    return () => {
      source.element?.removeEventListener('pointerdown', handleStart);
    };
  }
}

With Activation Constraints

import {
  Sensor,
  ActivationController,
  ActivationConstraint,
  type ActivationConstraints
} from '@dnd-kit/abstract';

class DelayConstraint extends ActivationConstraint<PointerEvent> {
  private timeout?: number;
  
  onEvent(event: PointerEvent): void {
    this.timeout = window.setTimeout(() => {
      this.activate(event);
    }, this.options.delay);
  }
  
  abort(): void {
    if (this.timeout) {
      clearTimeout(this.timeout);
    }
  }
}

class MySensor extends Sensor {
  public bind(source: Draggable): CleanupFunction {
    const handlePointerDown = (event: PointerEvent) => {
      const constraints: ActivationConstraints<PointerEvent> = [
        new DelayConstraint({delay: 200})
      ];
      
      const controller = new ActivationController(
        constraints,
        (event) => {
          // Activation confirmed
          this.manager.actions.start({
            source,
            event,
            coordinates: {x: event.clientX, y: event.clientY}
          });
        }
      );
      
      const handleMove = (event: PointerEvent) => {
        controller.onEvent(event);
      };
      
      const handleUp = () => {
        controller.abort();
        cleanup();
      };
      
      document.addEventListener('pointermove', handleMove);
      document.addEventListener('pointerup', handleUp);
      
      const cleanup = () => {
        document.removeEventListener('pointermove', handleMove);
        document.removeEventListener('pointerup', handleUp);
      };
    };
    
    source.element?.addEventListener('pointerdown', handlePointerDown);
    
    return () => {
      source.element?.removeEventListener('pointerdown', handlePointerDown);
    };
  }
}

Usage Examples

Using Sensors with Manager

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

const manager = new DragDropManager({
  sensors: [PointerSensor, KeyboardSensor]
});

Configuring Sensors

const manager = new DragDropManager({
  sensors: [
    PointerSensor.configure({
      activationConstraint: {
        distance: 10 // Require 10px movement
      }
    }),
    KeyboardSensor
  ]
});

Per-Draggable Sensors

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

const draggable = new Draggable(
  {
    id: 'item-1',
    sensors: [PointerSensor] // Override manager's sensors
  },
  manager
);

Dynamic Sensor Management

const manager = new DragDropManager();

// Add sensors later
manager.sensors = [PointerSensor, KeyboardSensor];

// Disable a sensor temporarily
const pointerSensor = manager.sensors.find(s => s instanceof PointerSensor);
pointerSensor?.disable();

// Re-enable
pointerSensor?.enable();

Extending Defaults

const manager = new DragDropManager({
  sensors: (defaults) => [
    ...defaults,
    CustomSensor
  ]
});

Common Sensor Patterns

Pointer Sensor Pattern

class PointerSensor extends Sensor {
  public bind(source: Draggable): CleanupFunction {
    const handlePointerDown = (event: PointerEvent) => {
      event.preventDefault();
      
      const controller = this.manager.actions.start({
        source,
        event,
        coordinates: {x: event.clientX, y: event.clientY}
      });
      
      const handlePointerMove = (event: PointerEvent) => {
        this.manager.actions.move({
          to: {x: event.clientX, y: event.clientY},
          event
        });
      };
      
      const handlePointerUp = (event: PointerEvent) => {
        this.manager.actions.stop({event});
        cleanup();
      };
      
      document.addEventListener('pointermove', handlePointerMove);
      document.addEventListener('pointerup', handlePointerUp);
      
      controller.signal.addEventListener('abort', cleanup);
      
      const cleanup = () => {
        document.removeEventListener('pointermove', handlePointerMove);
        document.removeEventListener('pointerup', handlePointerUp);
      };
    };
    
    source.element?.addEventListener('pointerdown', handlePointerDown);
    
    return () => {
      source.element?.removeEventListener('pointerdown', handlePointerDown);
    };
  }
}

Keyboard Sensor Pattern

class KeyboardSensor extends Sensor {
  public bind(source: Draggable): CleanupFunction {
    const handleKeyDown = (event: KeyboardEvent) => {
      if (event.key === 'Enter' || event.key === ' ') {
        // Start drag
        this.manager.actions.start({
          source,
          event,
          coordinates: {x: 0, y: 0}
        });
      }
      
      if (event.key === 'ArrowUp') {
        this.manager.actions.move({by: {x: 0, y: -10}, event});
      }
      // Handle other arrow keys...
    };
    
    source.element?.addEventListener('keydown', handleKeyDown);
    
    return () => {
      source.element?.removeEventListener('keydown', handleKeyDown);
    };
  }
}

See Also

• DragDropManager - Using sensors with the manager
• Draggable - Attaching sensors to draggables
• Plugins - Base plugin architecture
• Modifiers - Transforming drag behavior