Number Field
Steps of 0.5, grouped display on commit.
A locale-aware decimal field: a text input with role="spinbutton" and
inputmode="decimal", plus increment/decrement buttons. The field accepts
plain decimal numbers — the locale’s digits or ASCII digits, an optional sign,
group separators anywhere, one decimal separator. Currency, percent, unit,
compact, and scientific formats are not supported.
Import
Section titled “Import”<script> import NumberField from "@invisible-ui/svelte/NumberField.svelte";</script><script setup> import { NumberField } from "@invisible-ui/vue";</script>import { NumberField } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-number-field></ds-number-field>Value and draft
Section titled “Value and draft”The canonical value is a number (or null when empty); the text being
edited is a separate draft. While you type, onValueChange follows the draft
as it parses. On blur, Enter, or a spin action the field commits
(onValueCommit): a valid draft is reformatted into the locale’s display
(grouping included), an unparseable draft is kept exactly as typed and flagged
invalid — nothing is lost or silently corrected. Escape restores the last
committed value. A form submits the canonical ASCII value (for example
1234.5) through a hidden input, never the localized text.
Validation, not correction
Section titled “Validation, not correction”Typed input that violates min, max, or step keeps the value and reports
the violation (aria-invalid plus a localized message). The spin actions are
the corrective gesture: they snap to the nearest step multiple in the pressed
direction and stay inside the bounds. Stepping uses exact decimal arithmetic,
so ten steps of 0.1 land on 1, never 0.9999….
Keyboard and wheel
Section titled “Keyboard and wheel”- ArrowUp / ArrowDown step by
step. - Home / End jump to
min/maxwhen both are set; otherwise the keys keep their native caret meaning. - Enter commits without blocking form submission; Escape undoes the draft.
- Every other editing key, selection, and clipboard shortcut stays native.
- The wheel does nothing by default (the page keeps scrolling). Set
changeOnWheelto step while the input is focused and hovered.
Locale
Section titled “Locale”Parsing and display follow the locale prop, defaulting to the surrounding
Locale Provider
scope. The field accepts ASCII digits, the locale’s own digits, and
Arabic-Indic (٠–٩) and Persian (۰–۹) digits in every locale, typed or pasted.
The value it reports is a number, and the formatted text uses the locale’s
digits.
A locale that groups thousands with an apostrophe, such as de-CH, takes both
the typographic ’ it displays and the straight ' keyboards type. No other
locale takes an apostrophe, and a malformed number, such as 1'234,5 in
de-CH, stays invalid.
In Elements:
<ds-number-field label="Amount" name="amount" value="1234.5" min="0" step="0.5"></ds-number-field>The value attribute takes the canonical ASCII form. The element sends input
while the draft parses and change at each commit, both with detail.value.
increment-label and decrement-label override the localized button names.
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Visible label, tied to the control. |
value | number | null | null | The canonical value; null means empty. Bindable through onValueChange. |
locale | string | undefined | undefined | BCP-47 locale for parsing and display. Defaults to the provider's locale. |
min | number | undefined | undefined | |
max | number | undefined | undefined | |
step | number | 1 | Step for the spin actions; typed values are validated against it. |
disabled | boolean | false | |
readOnly | boolean | false | |
required | boolean | false | |
changeOnWheel | boolean | false | Opt in to wheel stepping while the input is focused and hovered. |
description | string | undefined | undefined | Optional hint shown under the control and linked via aria-describedby. |
error | string | undefined | undefined | Error message; when non-empty the field becomes invalid and announces it. |
name | string | undefined | undefined | Form field name; the canonical ASCII value is submitted under it. |
form | string | undefined | undefined | Id of the owning form when the field renders outside of it. |
onValueChange | ((value: number | null) => void) | undefined | undefined | Called when the canonical value changes while editing. |
onValueCommit | ((value: number | null) => void) | undefined | undefined | Called at commit boundaries: blur, Enter, and spin actions. |
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Visible label, tied to the control. |
modelValue | number | null | undefined | v-model value; takes precedence over value when bound. |
value | number | null | null | The canonical value; null means empty. |
locale | string | undefined | BCP-47 locale for parsing and display. Defaults to the i18n scope. |
min | number | undefined | |
max | number | undefined | |
step | number | 1 | Step for the spin actions; typed values are validated against it. |
disabled | boolean | false | |
readOnly | boolean | false | |
required | boolean | false | |
changeOnWheel | boolean | false | Opt in to wheel stepping while the input is focused and hovered. |
description | string | undefined | Optional hint shown under the control and linked via aria-describedby. |
error | string | undefined | Error message; when non-empty the field becomes invalid and announces it. |
name | string | undefined | Form field name; the canonical ASCII value is submitted under it. |
form | string | undefined | Id of the owning form when the field renders outside of it. |
onValueChange | (value: number | null) => void | undefined | Called when the canonical value changes while editing. |
onValueCommit | (value: number | null) => void | undefined | Called at commit boundaries: blur, Enter, and spin actions. |
| Event | Payload |
|---|---|
update:modelValue | value: number | null |
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Visible label, tied to the control. |
value | number | null | null | Initial (uncontrolled) or current (controlled) value; null means empty. |
locale | string | — | BCP-47 locale for parsing and display. Defaults to the provider's locale. |
min | number | — | |
max | number | — | |
step | number | 1 | Step for the spin actions; typed values are validated against it. |
disabled | boolean | false | |
readOnly | boolean | false | |
required | boolean | false | |
changeOnWheel | boolean | false | Opt in to wheel stepping while the input is focused and hovered. |
description | string | — | Optional hint shown under the control and linked via aria-describedby. |
error | string | — | Error message; when non-empty the field becomes invalid and announces it. |
name | string | — | Form field name; the canonical ASCII value is submitted under it. |
form | string | — | Id of the owning form when the field renders outside of it. |
onValueChange | (value: number | null) => void | — | Called when the canonical value changes while editing. |
onValueCommit | (value: number | null) => void | — | Called at commit boundaries: blur, Enter, and spin actions. |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | |
value | yes | canonical, e.g. 1234.5 |
locale | yes | |
min | yes | |
max | yes | |
step | yes | |
disabled | yes | |
readonly | yes | |
required | yes | |
change-on-wheel | yes | |
description | yes | |
error | yes | |
name | yes | |
form | yes | |
increment-label | yes | |
decrement-label | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: value (number or null).
Emits: bubbling input CustomEvent while editing and change CustomEvent at each commit, both with detail.value (number or null).
Accessibility
Section titled “Accessibility”- The input is a labelled
role="spinbutton"with truthfularia-valuemin,aria-valuemax,aria-valuenow, and a localizedaria-valuetext. - The spin buttons are named from the field label (“Increase Price”), stay out of the tab order per the spinbutton pattern, and disable at the bounds; pressing them keeps focus in the input.
- Description and error text are linked via
aria-describedby; validation messages are announced politely.
Example
Section titled “Example”<NumberField label="Price" value={19.5} min={0} step={0.5} name="price" />In React, onValueChange reports the value while the user types and
onValueCommit reports it at each commit boundary:
<NumberField label="Price" value={price} min={0} step={0.5} onValueCommit={setPrice} />Themeable via --ds-field-*.