Pointer Lock Movement

A pointer lock movement manager for customizing your own creative UI. Inspired by Figma's number input element: Dragging on an input label moves a virtual cursor continuously in an infinite looping area and slides the input's figure value.

This tool toggles pointer lock state when interacting with a specific element and continually delivers MouseEvents. You can configure its behavior as you like.

🧩 Installation

yarn add pointer-lock-movement (or npm/pnpm)

👇 Usage

import { isSupportPointerLock, pointerLockMovement } from 'pointer-lock-movement'

if (isSupportPointerLock()) {
    const cleanup = pointerLockMovement(TOGGLE_ELEMENT, OPTIONS);

    REQUEST_TO_DISPOSE_THE_LISTENED_EVENTS_CALLBACK(() => {
      cleanup()
    })
}

📎 Example

Enhance your input-number component:

const [value, setValue] = useState(0);

const pointerLockerRef = useRef<HTMLDivElement>(null)

useEffect(
  () => {
    if (!pointerLockerRef.current) {
      return
    }

    return pointerLockMovement(
      pointerLockerRef.current,
      {
          onMove: evt => setValue(val => val + evt.movementX),
          cursor: '⟺',
      }
    )
  },
  [],
)

return (
  <label>
    <div ref={resizeElRef}>⟺</div>
    <input value={value} onChange={e => setValue(e.currentTarget.value)} />
  </label>
)

See more examples:

1. Input Number
2. Magnifying Glass

👇 API

📝 Type Definition

type MoveState = {
    status: 'moving' | 'stopped',
    movementX: number,
    movementY: number,
    offsetX: number,
    offsetY: number,
}

type PointerLockMovementOption = {
    onLock?: (locked: boolean) => void,
    onMove?: (event: MouseEvent, moveState: MoveState) => void,
    cursor?: string | HTMLElement | Partial<CSSStyleDeclaration>,
    screen?: DOMRect | HTMLElement | Partial<CSSStyleDeclaration>,
    zIndex?: number,
    loopBehavior?: 'loop' | 'stop' | 'infinite',
    trigger?: 'drag' | 'toggle',
}

• onLock registers callback to listen locking state changing
• onMove registers callback to listen mouse movement, it carries the corresponding event and the moving state. If the loopBehavior is configured to stop and the virtual cursor reached the edge of the screen, the moveState.status will be read as stopped.
• cursor is used as the virtual cursor. By default, the cursor is an empty DIV element:
  • if it is a string, it will be used as the cursor's text content,
  • if it is an HTMLElement, it will be used as the virtual cursor,
  • if it is an object with a snake-case property names, it will be applied as the cursor's CSS style.
• screen is used as the virtual screen, it usually defines the edges of the virtual cursor. By default, we count the edges of the browser's viewport.
  • if it is a DOMRect, it will be assumed as the size and position information of the virtual screen,
  • if it is an HTMLElement, it will be rendered into the DOM structure,
  • if it is an object with a snake-case property name, it will be regarded as the CSS style and render a virtual screen element with this style.
• zIndex is used as the z-index CSS property of the virtual cursor/screen with the default value 99999, it is useful when there are other elements over it.
• loopBehavior is used to control the behavior of the virtual cursor when it reaches the edge of the screen. By default, it is loop.
  • loop: the virtual cursor will be moved to the other side of the screen
  • stop: the virtual cursor will be stopped at the edge of the screen
  • infinite: the virtual cursor will be moved out of the screen
• trigger is used to control the triggering way of the virtual cursor. By default, it is drag.
  • drag: the virtual cursor movement will be toggled by pointer-down and pointer-up events.
  • toggle: the virtual cursor movement will be toggled by pointer events.