Comment on page
Keyboard
The Keyboard sensor responds to Keyboard events. It is one of the default sensors used by the DndContext provider if none are defined.
In order for the Keyboard sensor to function properly, the activator element that receives the
useDraggable listeners must be able to receive focus. To learn more, read the in-depth Accessibility guide.The keyboard activator is the
onKeyDown event handler. The Keyboard sensor is initialized if the event.code property matches one of the start keys passed to keyboardCodes option of the Keyboard sensor.By default, the keys that activate the Keyboard sensor are
Space and Enter.This option represents the keys that are associated with the drag
start, cancel and end events. The keyboardCodes options adheres to the following interface:type KeyboardCode = KeyboardEvent['code'];
interface KeyboardCodes {
start: KeyboardCode[];
cancel: KeyboardCode[];
end: KeyboardCode[];
};
The default values are:
const defaultKeyboardCodes = {
start: ['Space', 'Enter'],
cancel: ['Escape'],
end: ['Space', 'Enter'],
};
You can customize these values, but keep in mind that the third rule of ARIA requires that a user must be able to activate the action associated with a draggable widget using both the
enter (on Windows) or return (on macOS) and the space key. To learn more, read the in-depth accessibility guide.Keep in mind that you should also customize the screen reader instructions using the
screenReaderInstructions prop of <DndContext> if you update these values, as the screen reader instructions assume that the Keyboard sensor is initialized with the default keyboard shortcuts.The
move keyboard codes are not a customizable option, because those are handled by the coordinate getter function. To customize them, write a custom coordinate getter function.By default, the Keyboard sensor moves in any given direction by
25 pixels when any of the arrow keys are pressed while dragging.This is an arbitrary sensible default that may or may not be suited to the use case you are building.
The
getNextCoordinates option can be used to define a custom coordinate getter function that is passed the latest keyboard event along with the current coordinates:function customCoordinatesGetter(event, args) {
const {currentCoordinates} = args;
const delta = 50;
switch (event.code) {
case 'Right':
return {
...currentCoordinates,
x: currentCoordinates.x + delta,
};
case 'Left':
return {
...currentCoordinates,
x: currentCoordinates.x - delta,
};
case 'Down':
return {
...currentCoordinates,
y: currentCoordinates.y + delta,
};
case 'Up':
return {
...currentCoordinates,
y: currentCoordinates.y - delta,
};
}
return undefined;
};
While the example above is fairly simple, you can build complex coordinate getters to support advanced use cases. The Sortable preset uses the
getNextCoordinates option to build on top of the Keyboard sensor and move the active sortable item to its new index depending on the arrow key that is pressed.This option represents the scroll behavior that should be used when scrolling to new coordinates. The default value is
smooth, which results in the scroll container being scrolled smoothly to the new coordinates. The other possible value is
auto, which results in the scroll container being scrolled directly to the new coordinates without any animation.Last modified 2yr ago