NumberField

Composable numeric input with formatted text entry, spinbutton semantics, stepper buttons, optional wheel scrubbing, and pointer scrubbing.

value: 42

Anatomy

NumberField.Root provides state to every part. Group wraps the visible controls, Input is the spinbutton text input, and Decrement / Increment are the stepper buttons. ScrubArea (with an optional ScrubAreaCursor) adds pointer scrubbing.

<script>
	import { NumberField } from '@human-kit/ui';
</script>

<NumberField.Root>
	<NumberField.ScrubArea>
		<NumberField.ScrubAreaCursor />
	</NumberField.ScrubArea>
	<NumberField.Group>
		<NumberField.Decrement />
		<NumberField.Input />
		<NumberField.Increment />
	</NumberField.Group>
</NumberField.Root>

Formatting

The visible text is formatted with Intl.NumberFormat via formatOptions, while bind:value always stays a raw number | null. Wrap the component in LocaleProvider to control locale-aware parsing and formatting.

raw value: 1234.5

Scrubbing

NumberField.ScrubArea turns any element into a pointer-drag control for the value, and allowWheelScrub lets the mouse wheel step the value while the input is focused. Both expose data-scrubbing for styling.

Drag to scrub

value: 12

Usage guidelines

  • Provide an accessible name for NumberField.Input with aria-label, aria-labelledby, or a visible <label for>.
  • Use bind:value for two-way state. The value is always number | null; the visible input text is formatted separately.
  • Wrap the component in LocaleProvider to control locale-aware parsing and formatting.
  • With allowOutOfRange={false}, out-of-range drafts remain editable while focused and clamp to min or max on commit.
  • Percent formatting treats % as a localized display suffix: typing 50 publishes 50, not 0.5.
  • Use name on Root only when the component should submit a raw numeric value in an HTML form.
  • incrementAriaLabel and decrementAriaLabel override the localized defaults when custom control names are needed.

Accessibility

  • NumberField.Input renders a text input with role="spinbutton" and exposes aria-valuemin, aria-valuemax, aria-valuenow, and aria-valuetext when applicable.
  • Arrow keys step by step, Shift + arrows step by largeStep, Ctrl/Cmd + arrows step by smallStep, and PageUp / PageDown and Home / End are supported.
  • Pointer scrub has equivalent input, keyboard, and button controls.
  • Invalid drafts and out-of-range values set native custom validity on the visible input so form submission is blocked while the field is invalid.

API reference

Root

The number field container. Owns the numeric state, formatting, and validation, provides context to all parts, and renders a hidden input that submits the raw number when `name` is set.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the field is disabled.
data-focus-within Present while any part of the field has focus.
data-invalid Present when the field is invalid.
data-number-field-hidden-input Identifies the hidden native input used for form submission.
data-number-field-root Identifies the root element.
data-readonly Present when the field is readonly.
data-required Present when the field is required.
data-scrubbing Present while a pointer scrub is in progress.

Group

Groups the visible controls (input and stepper buttons) and mirrors the field state through data attributes.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the field is disabled.
data-focus-within Present while any part of the field has focus.
data-invalid Present when the field is invalid.
data-number-field-group Identifies the group element.
data-readonly Present when the field is readonly.
data-required Present when the field is required.
data-scrubbing Present while a pointer scrub is in progress.

Input

The visible text input with role="spinbutton". Handles formatted text entry, keyboard stepping, and native validity.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the field is disabled.
data-focus-visible Present while focus should be visibly indicated (keyboard modality).
data-focused Present while the input has focus.
data-input-state Relation between the draft text and the committed value: "synced", "partial", "invalid", or "out-of-range".
data-invalid Present when the field is invalid.
data-number-field-input Identifies the input element.
data-out-of-range Present while the current value is outside `min`/`max`.
data-readonly Present when the field is readonly.
data-required Present when the field is required.
data-scrubbing Present while a pointer scrub is in progress.

Increment

Stepper button that increases the value by `step`. Excluded from the tab order and labeled with a localized default.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Decrement

Stepper button that decreases the value by `step`. Excluded from the tab order and labeled with a localized default.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

ScrubArea

Turns its content into a pointer-drag control that steps the value while dragging.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-direction The configured scrub direction ("horizontal" or "vertical").
data-disabled Present when the field is disabled.
data-invalid Present when the field is invalid.
data-number-field-scrub-area Identifies the scrub area element.
data-readonly Present when the field is readonly.
data-scrubbing Present while a pointer scrub is in progress.

ScrubAreaCursor

Optional virtual cursor rendered while scrubbing, following the pointer inside the scrub area.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the field is disabled.
data-invalid Present when the field is invalid.
data-number-field-scrub-area-cursor Identifies the scrub area cursor element.
data-readonly Present when the field is readonly.
data-scrubbing Present while a pointer scrub is in progress.