API reference

The full NumberField surface: props, the two-way modelValue model, the change event, and the imperative handle. For the per-framework consumption code see the usage page.

Props

The full prop surface. The single model: true slice (modelValue, the Two-way column) is an optional two-way r-model with an uncontrolled fallback; as the sole model prop it drives the Angular ControlValueAccessor, so a number field is a form control.

Name	Type	Default	Two-way (model)	Required	Description
modelValue	Number	null	✓		The numeric value of the field (two-way r-model). null means the field is empty. As the sole model: true prop it drives the Angular ControlValueAccessor, so a number field is a form control ([(ngModel)] / [formControl] bind directly). The value is clamped to [min, max] and snapped to step on every commit.
min	Number	null			Inclusive lower bound. Every commit clamps the value to >= min, and the Home key jumps to min. null (the default) means no lower bound. Also emitted as aria-valuemin.
max	Number	null			Inclusive upper bound. Every commit clamps the value to <= max, and the End key jumps to max. null (the default) means no upper bound. Also emitted as aria-valuemax.
step	Number	1			The increment/decrement granularity. ArrowUp / ArrowDown and the +/- buttons change the value by step, and every commit snaps the value to the nearest multiple of step measured from min (or 0 when min is null).
largeStep	Number	10			The coarse step applied by PageUp / PageDown, for fast traversal of a wide range.
formatOptions	Object	{}			Options forwarded to Intl.NumberFormat for locale-aware display formatting (e.g. { style: "currency", currency: "USD" } or { minimumFractionDigits: 2 }). The displayed text is formatted while the field is unfocused; on commit the formatting is stripped back off and the raw number is parsed.
allowScrub	Boolean	false			Opt in to scrub-on-drag: press and drag horizontally on the field to change the value by step per few pixels (a power-user affordance). Off by default.
disabled	Boolean	false			Disable the whole control — the input, both steppers, the keyboard, and scrubbing. Also sets the Angular ControlValueAccessor disabled state.
readonly	Boolean	false			Make the field read-only — the value is shown and focusable but cannot be changed by typing, the steppers, the keyboard, or scrubbing.
ariaLabel	String	null			Accessible name applied to the role="spinbutton" input (aria-label). Provide this (or an external <label>) so the control is announced.

Models (the two-way value)

modelValue is the one model: true prop — number | null, where null is the empty field. Two-way bind it (r-model:modelValue / v-model:modelValue / bind:modelValue / [(modelValue)]) and the component writes the new clamped + snapped value back on every commit. Left unbound it falls back to an uncontrolled default.

Model (r-model:)	Shape	Change event	Description
modelValue	number | null	change	The numeric value (null = empty). Written back clamped to [min, max] and snapped to step on every commit. As the sole model prop it drives the Angular ControlValueAccessor.

Events

Event	Description
change	Fired on every committed change — a typed value committed on blur/Enter, a step (buttons / Arrow / Page / Home / End), a scrub, or a programmatic increment/decrement/clear. Payload { value } — the new clamped + snapped number, or null when empty.

Imperative handle

Declared once via $expose; obtained through each framework's native ref mechanism.

Method	Description
focus	Move DOM focus to the input and select its text. Deliberately overrides the inherited HTMLElement.focus on the Lit custom element (accepted, warn-only ROZ137).
increment	Step the value up by one step (clamped + snapped). Emits change.
decrement	Step the value down by one step (clamped + snapped). Emits change.
clear	Set the value to null (empty) and clear the edit buffer. Emits change.

Slots

NumberField declares no slots — the +/- steppers and the input are built in. Re-skin via the --rozie-number-field-* tokens (see the showcase).