Number input component

components specs/components/number-input.kmd

A numeric field with increment/decrement steppers, min/max/step bounds, precision, and locale-aware formatting — the base for quantities, counts, durations, and dimensions. The generic sibling that money-input and phone-input specialize. Spectrum (number field / stepper) + Carbon (number input) parity.

When this spec applies

Primary triggers

All triggers

Component — Number input

Status: v0.1.0 — Draft. Promoted from the Adobe Spectrum parity scan (meta/docs/stack #094); also the generic Carbon "number input". Source: https://spectrum.adobe.com/page/number-field/

R1 — Value, bounds, step

  • A numeric value with optional min, max, and step (default step 1). The field clamps to [min, max]; out-of-range entry shows an inline message (specs/errors/user-facing-messages.kmd) and clamps on blur — never silently.
  • Precision: integers vs decimals are explicit; the step and precision agree (a step of 0.1 implies one decimal place).

R2 — Steppers (spin buttons)

  • Increment / decrement controls (the +/- spin buttons) change the value by one step, holding at the bounds (disabled at min/max).
  • They are real buttons with accessible labels ("Increase quantity"); a press-and-hold MAY repeat with acceleration.

R3 — Keyboard & wheel

  • ↑/↓ increment/decrement by step; PageUp/PageDown by a larger stride (e.g. 10×); Home/End jump to min/max.
  • Mouse wheel adjusts only while the field is focused (never on incidental scroll-over).
  • Typing is allowed; reject non-numeric characters; inputmode="numeric" for integers, decimal when decimals are allowed.

R4 — Formatting & parsing

  • Display uses locale digit grouping/decimal separators (specs/i18n/contract.kmd); parsing accepts the locale separators + optional sign. Store a canonical number, not the formatted string (specs/data/field-types.kmd).
  • Empty ≠ zero (empty = unset).

R5 — When to use vs slider / money

  • Use a number input for precise/large-range numeric entry.
  • Use a slider (specs/components/sliders.kmd) for approximate values in a small bounded range; pair them when both precision and feel matter.
  • money-input (specs/components/money-input.kmd) specializes this for currency (per-currency precision + minor-unit storage); phone-input for phone numbers. Do not rebuild those here.

R6 — Accessibility & i18n

  • role="spinbutton" (or native) with aria-valuenow/min/max/text; the steppers and field share one accessible label.
  • The current value + bounds are announced; clamping is announced, not silent.
  • All formatting is locale-aware; the stored numeric value is locale-invariant.

Não-escopo

  • Currency (specs/components/money-input.kmd) and phone (specs/components/phone-input.kmd) specializations.
  • Range/approximate selection (specs/components/sliders.kmd).
  • Unit conversion / calculated fields (product logic).

References