Keyboard Sensor

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: ['KeyW'],
    down: ['KeyS'],
    left: ['KeyA'],
    right: ['KeyD'],

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

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 codes 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['code'];

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:

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

Best Practices

Provide clear focus indicators:
- Use visible focus rings
- Maintain sufficient contrast
Support screen readers:
- Use proper ARIA attributes
- Provide clear instructions
Consider key combinations:
- Avoid conflicts with browser shortcuts
- Support standard keyboard patterns