Skip to main content

Number

Numeric input that captures a single numeric value via <input type="number">. Supports min, max, and step, browser spinner controls, and the full validation vocabulary (valid, invalid, helper text via aria-describedby).

Usage​

When to use

  • A single numeric value with a known range or step (counts, ages, quantities, durations expressed as a number)
  • Forms that benefit from the native browser spinner and numeric keypad on touch devices
  • Bounded values where min, max, and step express the constraint at the platform level

When not to use

  • A continuous slider input where the visual range matters - use range
  • A free-form code, identifier, or postal code that happens to contain digits - use textfield
  • A formatted currency or percentage that needs locale-aware display - use textfield with formatting on submit

Do

  • Set min, max, and step whenever the acceptable values are known
  • Pair the input with a visible label and helper text describing the unit
  • Mark required fields via the required attribute so the adjacent label auto-marks with an asterisk

Don't

  • Don't disable the native spinner without an alternative way to step the value
  • Don't use placeholder as a substitute for label or helper
  • Don't restrict character entry beyond what min, max, and step already enforce

API​

Slots​

SlotRequiredDescription
labelYesVisible label text for the number input.
helper-Helper text rendered after the input.

Props​

PropTypeDefaultDescription
namestring-Name attribute for form submission.
idstring-HTML id of the input. Used to associate the label. Generated when omitted.
valuenumber-Pre-filled numeric value.
placeholderstring-Placeholder text shown when the input is empty.
minnumber-Minimum allowed value.
maxnumber-Maximum allowed value.
stepnumber-Step increment for the spinner.
is_disabledboolean-Renders the disabled attribute on the input.
is_readonlyboolean-Renders the readonly attribute on the input.
is_requiredboolean-Renders the required attribute on the input.
is_invalidboolean-Marks the control as invalid. Renders aria-invalid="true" when set.
helper_idstring-ID applied to the helper element. Input gets aria-describedby pointing to it.
autocompletestring-Value for the autocomplete attribute.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.

Examples​

Sizes​

Sm, default, and lg variants stacked vertically. Font size and padding scale together.

Bounded​

Numeric input with min, max, and step constraints.

Required​

Required input with the adjacent label auto-marking via the asterisk rule.

States​

Disabled and read-only states.

Invalid​

Invalid validation state with helper text.

Accessibility​

  • WCAG 2.2 AA
  • Native <input type="number"> exposes the spinbutton role and announces min, max, and step
  • Helper text is associated via aria-describedby so assistive tech announces it after the field name
  • Validation states use aria-invalid="true|false" so the state is announced without color alone
  • Required state is announced via the required attribute, not the visual asterisk

Dependencies​

  • textfield - shared base styling and helper-text composition
  • textfield - free-form text input (use for IDs, postal codes, formatted numbers)
  • range - continuous slider for visually expressing a range of numeric values