Skip to content

Number Field

Locale

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.

<script>
import NumberField from "@invisible-ui/svelte/NumberField.svelte";
</script>

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.

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

  • ArrowUp / ArrowDown step by step.
  • Home / End jump to min / max when 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 changeOnWheel to step while the input is focused and hovered.

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.

PropTypeDefaultDescription
label *string—Visible label, tied to the control.
valuenumber | nullnullThe canonical value; null means empty. Bindable through onValueChange.
localestring | undefinedundefinedBCP-47 locale for parsing and display. Defaults to the provider's locale.
minnumber | undefinedundefined
maxnumber | undefinedundefined
stepnumber1Step for the spin actions; typed values are validated against it.
disabledbooleanfalse
readOnlybooleanfalse
requiredbooleanfalse
changeOnWheelbooleanfalseOpt in to wheel stepping while the input is focused and hovered.
descriptionstring | undefinedundefinedOptional hint shown under the control and linked via aria-describedby.
errorstring | undefinedundefinedError message; when non-empty the field becomes invalid and announces it.
namestring | undefinedundefinedForm field name; the canonical ASCII value is submitted under it.
formstring | undefinedundefinedId of the owning form when the field renders outside of it.
onValueChange((value: number | null) => void) | undefinedundefinedCalled when the canonical value changes while editing.
onValueCommit((value: number | null) => void) | undefinedundefinedCalled at commit boundaries: blur, Enter, and spin actions.
  • The input is a labelled role="spinbutton" with truthful aria-valuemin, aria-valuemax, aria-valuenow, and a localized aria-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.
<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-*.