useKeyboardMotionSensor

A React hook that creates a KeyboardMotionSensor instance for handling keyboard-based motion events with continuous movement.

Usage

import { useRef, useMemo, useCallback } from 'react';
import { useKeyboardMotionSensor, useDraggable } from 'dragdoll-react';

function DraggableItem() {
  const elementRef = useRef<HTMLDivElement | null>(null);
  const [keyboardMotionSensor, setKeyboardMotionSensorElementRef] = useKeyboardMotionSensor();
  const draggableSettings = useMemo(
    () => ({
      elements: () => (elementRef.current ? [elementRef.current] : []),
    }),
    [],
  );
  const draggable = useDraggable([keyboardMotionSensor], draggableSettings);
  const setRefs = useCallback(
    (node: HTMLDivElement | null) => {
      elementRef.current = node;
      setKeyboardMotionSensorElementRef(node);
    },
    [setKeyboardMotionSensorElementRef],
  );

  return (
    <div ref={setRefs} tabIndex={0} style={{ position: 'relative' }}>
      Content
    </div>
  );
}

Signature

function useKeyboardMotionSensor<E extends KeyboardMotionSensorEvents = KeyboardMotionSensorEvents>(
  settings?: Partial<KeyboardMotionSensorSettings<E>>,
  element?: Element | null,
): readonly [KeyboardMotionSensor<E> | null, (node: Element | null) => void];

Parameters

settings

type settings = Partial<KeyboardMotionSensorSettings<E>>;

Configuration settings for the keyboard motion sensor. See core KeyboardMotionSensor settings for all available settings.

WARNING

You MUST memoize the settings object (e.g. with useMemo) to prevent unnecessary re-evaluations and performance issues.

In addition to the core settings, the following event callback props are supported:

onStart

type onStart = (e: E['start']) => void;

A callback function that is called when the sensor starts. Optional.

onMove

type onMove = (e: E['move']) => void;

A callback function that is called when the sensor moves. Optional.

onCancel

type onCancel = (e: E['cancel']) => void;

A callback function that is called when the sensor is cancelled. Optional.

onEnd

type onEnd = (e: E['end']) => void;

A callback function that is called when the sensor ends. Optional.

onDestroy

type onDestroy = (e: E['destroy']) => void;

A callback function that is called when the sensor is destroyed. Optional.

onTick

type onTick = (e: E['tick']) => void;

A callback function that is called on each tick during continuous motion. This is specific to motion sensors. Optional.

IMPORTANT

The callbacks do not have to be memoized, you can pass new functions every time. Internally, the hook will store the latest callback in a ref and bind a proxy callback to the event listener, which in turn will call the latest callback.

• Optional.
• Default: {}.

element

type element = Element | null;

The element to attach the sensor to. If you want to attach the sensor to an element that is not managed by React, you can provide the element as the second parameter to the hook. In other cases it's recommended to always use the callback ref which is returned from the hook as the second value in the array.

• Optional.
• Default: undefined.

Return Value

type returnValue = readonly [KeyboardMotionSensor<E> | null, (node: Element | null) => void];

Returns a read-only array with two elements:

1. keyboardMotionSensor
   • The KeyboardMotionSensor instance, or null if not yet initialized.
2. setKeyboardMotionSensorElementRef
   • A ref callback to attach sensor to an element. This is the recommended way to attach the sensor to an element. You can alternatively provide an explicit element as the second parameter to the hook.

Notes

• The sensor instance is automatically destroyed when the component unmounts.
• Settings can be updated dynamically and will be applied to the sensor.
• If the element changes, the sensor is recreated with the new element.
• The sensor will be null initially until an element is attached.
• Make sure the element is focusable (e.g., with tabIndex={0}).

Types

UseKeyboardMotionSensorSettings

// Import
import type { UseKeyboardMotionSensorSettings } from 'dragdoll-react';

// Interface
interface UseKeyboardMotionSensorSettings<
  E extends KeyboardMotionSensorEvents = KeyboardMotionSensorEvents,
> extends Partial<KeyboardMotionSensorSettings<E>> {
  onStart?: (e: E['start']) => void;
  onMove?: (e: E['move']) => void;
  onCancel?: (e: E['cancel']) => void;
  onEnd?: (e: E['end']) => void;
  onDestroy?: (e: E['destroy']) => void;
  onTick?: (e: E['tick']) => void;
}