Advanced Primitives

These exports are intentionally low-level. Most apps should use useNumberFieldState, useNumberField, or the NumberField components.

Import

import {
  useControllableState,
  usePressAndHold,
  useScrubArea,
  NumberFieldContext,
  useNumberFieldContext,
} from "raqam";

useControllableState(options)

Tiny controlled/uncontrolled state helper used internally by raqam.

const [value, setValue] = useControllableState<number | null>({
  value: controlledValue,
  defaultValue: 0,
  onChange: setControlledValue,
});

Use it when you are building your own wrapper component and want the same controlled/uncontrolled semantics as NumberField.Root.

usePressAndHold(callback, options)

Returns pointer handlers that fire once immediately, then repeat with acceleration while the pointer stays down.

const hold = usePressAndHold(() => stepBy(1), {
  delay: 400,
  interval: 200,
  disabled,
});

<button type="button" {...hold}>+</button>

Options:

Option	Default	Description
delay	400	Milliseconds before repeating starts.
interval	200	Initial repeat interval; it accelerates down to a 50ms floor.
disabled	false	Disables the handlers.

useScrubArea(state, options)

Pointer Lock powered drag-to-adjust behavior for custom scrub handles.

const { scrubAreaProps, isScrubbing } = useScrubArea(state, {
  direction: "horizontal",
  pixelSensitivity: 4,
});

<span {...scrubAreaProps}>
  Drag to adjust {isScrubbing ? "…" : null}
</span>

Options:

Option	Default	Description
direction	"horizontal"	"horizontal", "vertical", or "both".
pixelSensitivity	4	Drag distance required for each step.

Return value:

Key	Description
isScrubbing	Whether pointer lock is active.
scrubAreaProps	Props to spread onto the scrub handle element.
virtualCursor	Pointer-lock cursor coordinates for custom overlays.

NumberFieldContext / useNumberFieldContext()

Context escape hatch for advanced compound components.

function CustomAdornment() {
  const { state } = useNumberFieldContext();
  return <span>{state.inputValue}</span>;
}

The context value exposes:

Key	Description
state	Current NumberFieldState.
aria	Current NumberFieldAria prop bags.
inputRef	Ref for the active input element.
props	Root props passed into NumberField.Root.

Caution

These APIs are intended for library authors or advanced composition. Prefer the documented higher-level APIs unless you specifically need custom primitives or design-system wrappers.