Keyboard Sensor

Detect keyboard input to initiate drag and drop operations.

Overview

The Keyboard sensor enables keyboard-based drag and drop interactions. It is enabled by default in the DragDropManager.

Usage

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

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

Default Key Bindings

The Keyboard sensor comes with these default key bindings:

const defaultKeyboardCodes = {
  start: ['Space', 'Enter'],          // Start dragging
  cancel: ['Escape'],                 // Cancel drag operation
  end: ['Space', 'Enter', 'Tab'],     // End dragging
  up: ['ArrowUp'],                    // Move up
  down: ['ArrowDown'],                // Move down
  left: ['ArrowLeft'],                // Move left
  right: ['ArrowRight'],              // Move right
};

Customizing Key Bindings

You can customize which keys trigger different actions:

KeyboardSensor.configure({
  keyboardCodes: {
    // Use Tab to start/end dragging
    start: ['Tab'],
    end: ['Tab'],

    // Use WASD for movement
    up: ['w'],
    down: ['s'],
    left: ['a'],
    right: ['d'],

    // Additional cancel keys
    cancel: ['Escape', 'q'],
  },
});

Key bindings are matched against KeyboardEvent.key, so they respect keyboard layouts and operating system key remaps. Use KeyboardEvent.key values such as w, Enter, and ArrowUp. The Space alias is also supported for the Space key.

If you are migrating a configuration that used KeyboardEvent.code, common Key* and Digit* values such as KeyW and Digit1 are normalized for compatibility. Other physical key codes, such as NumpadEnter, BracketLeft, or Slash, should be replaced with the key value they produce. Other named keys must match KeyboardEvent.key casing.

Default behavior

By default, each arrow key press moves the dragged item by 10 pixels. Hold Shift to multiply movement by 5 (so 50 pixels with the default offset).

API Reference

Options

keyboardCodes · KeyboardCodes

Configure which keyboard keys trigger different actions:

interface KeyboardCodes {
  start: KeyCode[];    // Start dragging
  cancel: KeyCode[];   // Cancel operation
  end: KeyCode[];      // End dragging
  up: KeyCode[];       // Move up
  down: KeyCode[];     // Move down
  left: KeyCode[];     // Move left
  right: KeyCode[];    // Move right
}

type KeyCode = KeyboardEvent['key'];

offset · number | {x: number; y: number} · default: "10"

The number of pixels to move the dragged item per arrow key press. Pass a single number to apply equally to both axes, or an object to set per-axis values. Hold Shift while pressing an arrow key to multiply this offset by 5.

KeyboardSensor.configure({
  offset: {x: 20, y: 10}, // Move 20px horizontally, 10px vertically per key press
});

preventActivation · (event: KeyboardEvent, source: Draggable) => boolean

Return true to prevent the sensor from starting a drag for a given keydown event. By default, the sensor only activates when the keyboard event’s target is the draggable’s handle (or its element if no handle is set) — preventing accidental drags from focused descendants like buttons or inputs.

KeyboardSensor.configure({
  preventActivation: (event, source) => {
    // Don't activate while a text input inside the draggable has focus
    return event.target instanceof HTMLInputElement;
  },
});

Events

The Keyboard sensor handles these events:

• keydown: Key press detection
• keyup: Key release detection

Activation

The sensor activates when:

1. A draggable element or its handle has focus
2. A configured start key is pressed
3. The element isn’t disabled

Best Practices

1. Provide clear focus indicators:

   • Use visible focus rings
   • Maintain sufficient contrast

2. Support screen readers:

   • Use proper ARIA attributes
   • Provide clear instructions

3. Consider key combinations:

   • Avoid conflicts with browser shortcuts
   • Support standard keyboard patterns