NumberField

This is a numeric input. The text has a locale format, the input has spinbutton semantics, and the field has step buttons. The value can also change when the user drags a pointer or turns the mouse wheel.

Anatomy

NumberField.Root gives the state to each part. Group contains the controls that the user sees. Input is the spinbutton text input. Decrement and Increment are the step buttons. ScrubArea adds the pointer drag control, and it can contain a ScrubAreaCursor.

<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>

Format

Intl.NumberFormat makes the text that the user sees, and formatOptions controls it. The value in bind:value is always a number or null. Put the component in a LocaleProvider to control the locale of the format and of the text that the component reads.

Pointer drag

NumberField.ScrubArea makes any element into a drag control for the value. The allowWheelScrub prop lets the mouse wheel change the value while the input has the focus. Both parts show data-scrubbing for the styles.

Drag to scrub

Usage guidelines

Give NumberField.Input an accessible name with aria-label, with aria-labelledby, or with a <label for> element that the user sees.
Use bind:value for the state in the two directions. The value is always a number or null. The component makes the text separately.
Put the component in a LocaleProvider to control the locale of the format and of the text that the component reads.
With allowOutOfRange={false}, the user can edit a value that is out of the range while the input has the focus. When the input loses the focus, the value goes to min or to max.
In a percent format, the % character is a localized suffix. If the user types 50, the value becomes 50, not 0.5.
Use name on Root only when the component must submit a raw numeric value in an HTML form.
Use incrementAriaLabel and decrementAriaLabel to replace the localized default names of the two buttons.

Accessibility

NumberField.Input makes a text input with role="spinbutton". When they apply, the component sets aria-valuemin, aria-valuemax, aria-valuenow, and aria-valuetext.
The arrow keys change the value by step. Shift and the arrow keys change it by largeStep. Ctrl or Cmd and the arrow keys change it by smallStep. The PageUp, PageDown, Home, and End keys also change the value.
The keyboard and the buttons do the same operations as the pointer drag.
A bad value or a value out of the range sets the native custom validity on the input. Thus the form does not submit while the field is not valid.

API reference

Root

The container of the number field. It holds the numeric state, the format, and the validation, and it gives the context to all of the parts. With a `name`, it also makes a hidden input that submits the raw number.

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 for the 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 the user drags the value with a pointer.

Group

Contains the controls that the user sees: the input and the step buttons. It shows the state of the field in 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 the user drags the value with a pointer.

Input

The text input that the user sees, with role="spinbutton". It controls the text with its format, the keyboard steps, and the 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 the focus must be visible (keyboard modality).

data-focused Present while the input has focus.

data-input-state The relation between the text in the input and the 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 value is less than `min` or more than `max`.

data-readonly Present when the field is readonly.

data-required Present when the field is required.

data-scrubbing Present while the user drags the value with a pointer.

Increment

The button that makes the value larger by `step`. It is not in the tab order, and it has a localized default name.

Prop Type Default

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

Decrement

The button that makes the value smaller by `step`. It is not in the tab order, and it has a localized default name.

Prop Type Default

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

ScrubArea

Makes its content into a drag control. While the user drags the pointer, the value changes.

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 the user drags the value with a pointer.

ScrubAreaCursor

An optional cursor, in the DOM while the user drags. It follows the pointer in the drag 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 the user drags the value with a pointer.