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
With error and mouse wheel
With currency prefix
With unit suffix
With large step
Read-only
Loading
Currency format with hint
Percent format
With negative values
Disabled
Clearable
Without step buttons
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/stepto match the real data. - Use
data-ts-number-formatfor prices and percentages. Users see “$12,500.50” and the form receives 12500.5. - Build it with the
fieldmarkup 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-wheeldata-ts-cleardata-ts-large-stepdata-ts-localedata-ts-numberdata-ts-number-fielddata-ts-number-formatdata-ts-number-rawdata-ts-number-spinnerdata-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-step | How far Page Up and Page Down jump, instead of step × 10. |
data-ts-allow-wheel | The mouse wheel only changes the value with this attribute. Without it, the scroll goes to the page. |
readonly | On 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-suffix | Prefix and suffix: markup and CSS. |
setNumberInputLoading(root, true | false) | Sets is-loading, aria-busy, and the Spinner. |
data-ts-number-format, data-ts-locale | data-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.csstaisho.icon.csstaisho.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-labeland become disabled when they reachmin/max. - The
labelis associated throughfor/id. - The hint text and the error message are linked to the field through
aria-describedby. An invalid field carriesaria-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-wheelon 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, respectingdeltaXanddeltaMode. - 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_INTEGERis clamped to that limit (a larger integer would silently lose digits). readonlysets 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’tdisabled, which also removes the field from the focus order.- For the loading state, call
setNumberInputLoading(root, true|false). It setsis-loadingandaria-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) anddata-ts-localeon the root, the field switches totype="text"withinputmode="decimal"androle="spinbutton", plusaria-valuenow(the raw number),aria-valuemin/aria-valuemax, andaria-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 negativeminor nomin, it goes through. - The prefix and suffix (
ts number-input-prefixandts 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 thelabel(for example, “Price in USD”). - The clear button (
data-ts-clear) carries itsaria-labelwritten in the HTML, appears only when there is a value, and not with adisabledorreadonlyfield. 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. |
| HomeEnd | Go to min / max. Without that limit, they keep their native behavior (moving the text caret). |
| Page UpPage Down | Jump 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.