Skip to content

NumberInput

A numeric field with increment and decrement buttons. It respects min, max, and step, responds to the arrow keys, and with data-ts-number-format shows currency, thousands separators, or percentages without losing the raw number.

Forms · TaishoDS Core, in plain HTML.

Examples

One working example per case. Each example is the HTML of its preview—copy it as is, and with Core’s CSS and JS loaded, it looks and works the same.

Quantity with min and max

html

With error and mouse wheel

html

With currency prefix

USD
html

With unit suffix

GB
html

With large step

html

Read-only

html

Loading

html

Currency format with hint

html

Percent format

html

With negative values

html

Disabled

html

Clearable

html

Without step buttons

USD
html

When to use

  • Capturing an exact amount with a defined step, like a quantity, age, or price.
  • It helps to adjust in steps with the buttons or arrow keys.
  • The precise value matters, not an approximation.

When not to use

  • The value is approximate within a range, and visual feedback helps → slider.
  • It isn’t a number but text → input.

Do

  • Set min/max/step to match the real data.
  • Use data-ts-number-format for prices and percentages. Users see “$12,500.50” and the form receives 12500.5.
  • Build it with the field markup for the label and errors.

Don’t

  • Don’t use it for huge ranges where typing is faster than stepping.
  • Don’t skip the limits. Letting any number through pushes the error downstream.

TaishoDS Core

Needs Core’s JS, which hooks in through data-ts-* attributes.

It’s built on a native <input>, but the +/− buttons and arrow-key stepping are its own.

Core hooks into it through these attributes. They go in the markup, and there’s nothing to initialize.

  • data-ts-allow-wheel
  • data-ts-clear
  • data-ts-large-step
  • data-ts-locale
  • data-ts-number
  • data-ts-number-field
  • data-ts-number-format
  • data-ts-number-raw
  • data-ts-number-spinner
  • data-ts-number-step

What it does: Increments and decrements within min, max, and step, and restores the last valid value on blur. Home and End go to min and max (only if they’re set). Page Up and Page Down jump by step × 10. The text isn’t rewritten while you type, and a number beyond ±Number.MAX_SAFE_INTEGER is clamped on blur. With min at 0 or above, the - sign isn’t accepted.

Attribute What it does
data-ts-large-stepHow far Page Up and Page Down jump, instead of step × 10.
data-ts-allow-wheelThe mouse wheel only changes the value with this attribute. Without it, the scroll goes to the page.
readonlyOn the input. The buttons are disabled, and neither the arrow keys, other keys, nor the wheel change the value.
ts number-input-prefix, ts number-input-suffixPrefix and suffix: markup and CSS.
setNumberInputLoading(root, true | false)Sets is-loading, aria-busy, and the Spinner.
data-ts-number-format, data-ts-localedata-ts-number-format is a JSON of Intl.NumberFormatOptions. The field becomes a text field and shows the formatted value, except while focused, when you edit the raw number. The raw value is submitted through the hidden data-ts-number-raw input.

From the CDN, without a build, load taisho.number-input.css along with taisho.base.css. Also load:

  • taisho.button.css
  • taisho.icon.css
  • taisho.spinner.css

For how Core works in general, see Behavior.

Accessibility

Implements the Spinbutton pattern from the WAI-ARIA APG.

  • The ↑/↓ arrow keys increment and decrement by step. Home/End and Page Up/Page Down follow the APG spinbutton pattern (React Aria ships them the same way).
  • The + / − buttons have their own aria-label and become disabled when they reach min/max.
  • The label is associated through for/id.
  • The hint text and the error message are linked to the field through aria-describedby. An invalid field carries aria-invalid="true".
  • The mouse wheel doesn’t change the value unless you enable it (and only while the field is focused) with data-ts-allow-wheel on the root. Without it, the field keeps focus—it isn’t released—and the scroll is forwarded to the nearest scrollable ancestor or to the page, respecting deltaX and deltaMode.
  • On blur with an empty or invalid field, the last valid value is restored. What the user sees and what the form submits always match.
  • The field’s text isn’t rewritten while typing. It’s only normalized on blur. A number beyond ±Number.MAX_SAFE_INTEGER is clamped to that limit (a larger integer would silently lose digits).
  • readonly sets the native attribute on the <input>. It stays focusable and copyable, the +/− buttons are disabled, and neither the arrow keys, the navigation keys, nor the wheel change the value. It isn’t disabled, which also removes the field from the focus order.
  • For the loading state, call setNumberInputLoading(root, true|false). It sets is-loading and aria-busy="true" on the <input>, and shows the Spinner at the end of the field. If you set only the class, it isn’t announced. It doesn’t block editing.
  • With data-ts-number-format (currency, thousands, percentage) and data-ts-locale on the root, the field switches to type="text" with inputmode="decimal" and role="spinbutton", plus aria-valuenow (the raw number), aria-valuemin/aria-valuemax, and aria-valuetext (the formatted value, so the screen reader says “$12,500.50” and not “12500.5”). Without focus, you see the formatted value. With focus, the raw number for editing. It only accepts digits, the decimal separator, and -.
  • With min >= 0, a typed minus sign isn’t accepted (it isn’t written and then corrected on blur). With a negative min or no min, it goes through.
  • The prefix and suffix (ts number-input-prefix and ts number-input-suffix, for a unit or currency) are decorative text next to the field. If the unit is key to understanding the value, repeat it in the label (for example, “Price in USD”).
  • The clear button (data-ts-clear) carries its aria-label written in the HTML, appears only when there is a value, and not with a disabled or readonly field. With it, an empty field is a valid state: it isn’t restored on blur, and focus returns to the field. If you leave out the −/+ buttons, ↑/↓ and the jump keys still work.

Keyboard

On top of what the browser already does (Tab moves focus, Enter activates a button).

Key What it does
↑↓Add or subtract step from the value (0.5 + 1 = 1.5), like the buttons.
HomeEndGo to min / max. Without that limit, they keep their native behavior (moving the text caret).
Page UpPage DownJump by the large step (data-ts-large-step on the root; ten times the step by default).

Verification

What was actually tested. Anything that wasn’t tested says so—we’d rather say “not verified” than claim too much.

  • axe WCAG 2.2 A + AA in a real browser, in light and dark mode, before every release.
  • keyboard Key map documented above, checked against the component.
  • screen reader Not verified with a screen reader. Test it in your own combination of components, not just here, where each one appears alone and on its happy path.