A pointer lock movement manager for customizing your own creative UI. Inspired by Figma's number input element: Dragging on an input label and moves a virtual cursor continuously in an infinite looping area and slides the input's figure value.
This tool toggles the pointer's lock state when user is interacting with a specific HTML element. Its registered callback is triggered when a mouse/trackPad/other pointing device delivers PointerEvent
under the pointer-locked state. You can configure its behaviors as you like.
yarn add pointer-lock-movement (or npm/pnpm)
import { isSupportPointerLock, pointerLockMovement } from 'pointer-lock-movement'
if (isSupportPointerLock()) {
const cleanup = pointerLockMovement(TOGGLE_ELEMENT, OPTIONS);
REQUEST_TO_DISPOSE_THE_LISTENED_EVENTS_CALLBACK(() => {
cleanup()
})
}
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:
Name | signature | description |
---|---|---|
isSupportPointerLock | () => boolean |
predicates pointer lock is supported |
pointerLockMovement | (element: Element, option?: PointerLockMovementOption) => () => void |
stars the pointer lock managing for a specific element and returns cleanup function |
type MoveState = {
status: 'moving' | 'stopped',
movementX: number,
movementY: number,
offsetX: number,
offsetY: number,
}
type PointerLockMovementOption = {
onLock?: (locked: boolean) => void,
onMove?: (event: PointerEvent, moveState: MoveState) => void,
cursor?: string | HTMLElement | Partial<CSSStyleDeclaration>,
screen?: DOMRect | HTMLElement | Partial<CSSStyleDeclaration>,
zIndex?: number,
loopBehavior?: 'loop' | 'stop' | 'infinite',
trigger?: 'drag' | 'toggle',
dragOffset?: number,
disableOnActiveElement?: number,
}
onLock
registers callback to listen locking state changingonMove
registers callback to listen pointer movement, it carries the corresponding event and the moving state. If theloopBehavior
is configured tostop
and the virtual cursor reached the edge of the screen, themoveState.status
will be read asstopped
.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 value99999
, 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 isloop
.loop
: the virtual cursor will be moved to the other side of the screenstop
: the virtual cursor will be stopped at the edge of the screeninfinite
: 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 isdrag
.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.
dragOffset
prevent invoking the pointer locker immediately until your pointer moves over the offset pixels.disableOnActiveElement
prevent pointer locking on active element. e.g. After attaching this feature on an input element, you may wish to select text range while it got focus.