Number input

A number input takes a number people type, such as an amount, a price, a rate, or a measurement. It can format the value as currency, a percent, or a unit, and has small ▲▼ buttons to step it. Wrap it in a Field for a label.

Stable

Figma

Overview

Usage

API

Accessibility

<tk-field label="Amount">
  <tk-number-input name="amount" format="currency" currency="USD" min="0" step="0.01" value="1234.5"></tk-number-input>
</tk-field>

Anatomy

Part	What it is
`tk-number-input`	the element; one Tab stop
`field` part	the bordered box
`input` part	the inner text field with the spinbutton role
`prefix` / `suffix` slots	optional text or icon before or after the value
`spinners` part	the ▲▼ pair at the trailing edge; press to step, hold to repeat

The label, help text, and error message come from a Field.

Formatting

<tk-field label="Price">
  <tk-number-input format="currency" currency="EUR" value="1250"></tk-number-input>
</tk-field>
<tk-field label="Completion">
  <tk-number-input format="percent" value="0.5" step="0.01"></tk-number-input>
</tk-field>

<tk-field label="Discount">
  <tk-number-input min="0" max="100" step="5" value="20"><span slot="suffix">%</span></tk-number-input>
</tk-field>

At rest, the field shows the formatted value ("$1,234.50"). On focus it shows the plain number ("1234.5"), so typing never fights separators. value stays a plain number.
format: decimal (default), currency with a currency code (USD if unset), percent, or unit with a unit such as kilometer. precision fixes the decimal places; locale sets the separators.
format="percent" treats the value as a fraction: 0.5 shows "50%". If your value is already 50, use a % suffix instead.
Affixes are decoration and are hidden from screen readers. Use format when the unit is part of the value.
For anything else Intl.NumberFormat supports, set the formatOptions property. It overrides the shorthand attributes.

Value and stepping

min, max, and step define the allowed values. People can type anything; when they leave the field, press Enter, or step, the value is clamped to the range and snapped to step.
▲▼ and the arrow keys change the value by step. Page Up, Page Down, and Shift with an arrow use large-step (a tenth of the range, or step × 10 with no range).
At min or max, the matching button is disabled. Stepping an empty field starts at min, or 0.
Negative numbers can be typed unless min is 0 or more.
The scroll wheel doesn't change the value. Set wheel to allow it, only while the field has focus.

Sizes

<tk-number-input aria-label="Medium number input" value="12"></tk-number-input>
<tk-number-input aria-label="Large number input" size="large" value="12"></tk-number-input>

`size`	Height	Padding-inline (start)	Value text
`medium` (default)	32px	`space-8`	Body Small (14/20)
`large`	36px	`space-10`	Body Medium (16/24)

The heights match medium and large buttons. There is no small; size="small" renders as medium and logs a console warning.

States

<tk-number-input aria-label="Seats included" value="25" readonly></tk-number-input>
<tk-number-input aria-label="Seats" value="25" disabled></tk-number-input>

<tk-field label="Seats" required error="Enter a number of seats from 1 to 500">
  <tk-number-input name="seats" min="1" max="500" value="900"></tk-number-input>
</tk-field>

The box works like an Input: no change on hover, and on focus its border takes the focus color and grows thicker inward. The ▲▼ buttons tint under the pointer.

readonly: people can focus and copy the value, but not change it. The ▲▼ buttons are hidden.
disabled: the field can't be focused or changed, and it's left out of the form.
Error: set error on the Field. The field clamps an out-of-range value but never shows an error on its own; you decide when and what to say.
Required: set required on the Field. Without a Field, set it on the number input.

When to use

If the value is	Use
a number people type: decimals, money, percent, units, a large or open range	Number input
a small whole number set with − and +, such as a quantity or guests	Number stepper
a value on a scale, set by dragging	Slider
digits that aren't a quantity: a postcode, a card or account number	Input with `inputmode="numeric"`
a one-time code	OTP input

Content

Label, help text, and error rules are the same as for Input. For a range error, give the range: "Enter a number of seats from 1 to 500".

Do / Don't

✅ Do	❌ Don't
Use Number input for quantities	Use it for postcodes, card numbers, or phone numbers
Store the numeric `value`	Store the formatted text
Set `min`, `max`, and `step` to the real range	Leave a bounded value unbounded
Use a `%` suffix when the value is already 50	Use `format="percent"`, which reads 50 as 5000%
Leave the scroll wheel off	Turn on `wheel` in a long scrolling form

Field: the label, help text, and error around a number input.
Number stepper: − and + buttons for small whole numbers.
Slider: set a value by dragging.
Input: text entry, and the route for digits that aren't a quantity.

API

Attributes

Attribute	Type	Default	What it does
`value`	number \| null	`null`	the number; `null` when empty; submits under `name`
`name`	string	—	the form field name
`min`	number	—	the lowest value; unset means no lower limit
`max`	number	—	the highest value; unset means no upper limit
`step`	number	`1`	the arrow and ▲▼ step, and the grid values snap to
`large-step`	number	—	the Page Up / Page Down and Shift step
`format`	`decimal` \| `currency` \| `percent` \| `unit`	`decimal`	how the value is shown at rest
`currency`	string	—	ISO 4217 code for `format="currency"`; `USD` if unset
`unit`	string	—	the unit for `format="unit"`, such as `kilometer`
`precision`	number	—	fixed number of decimal places
`locale`	string	—	the locale for separators, such as `de-DE`
`wheel`	boolean	`false`	lets the scroll wheel step the value while focused
`placeholder`	string	—	hint text shown while empty; avoid it
`inputmode`	string	`decimal` or `numeric`	the on-screen keyboard; `numeric` when only whole numbers fit
`autocomplete`	string	—	the autofill purpose, such as `transaction-amount`
`required`	boolean	`false`	the browser blocks submitting while empty
`readonly`	boolean	`false`	focusable and copyable, not editable; hides ▲▼
`disabled`	boolean	`false`	not focusable, not editable, left out of the form
`size`	`medium` \| `large`	`medium`	height 32 / 36px

Properties

formatOptions: an Intl.NumberFormatOptions object; overrides format, currency, unit, and precision.

Slots

Slot	Content
`prefix`	text or one `tk-icon` before the value, such as `$`
`suffix`	text or one `tk-icon` after the value, such as `%` or `kg`

Events

Event	When
`input`	on every edit and every step
`change`	when the value is committed: on blur, on Enter, and on every step

Holding a ▲▼ button fires one pair per repeat. Read the value property.

Methods

focus(): moves focus into the field.

CSS

::part(field): the bordered box.
::part(input): the inner text field.
::part(spinners): the ▲▼ pair.

Tokens

The box uses the Input tokens for every state. The ▲▼ buttons:

Role	Rest	Hover	Press	Disabled
glyph	`icon/default`	`icon/default`	`icon/default`	`icon/disabled`
background	none	`state/hover`	`state/press`	none

Each button is a radius-full pill, space-4 from the box's trailing edge. Affixes are text/secondary. Values per theme: Color.

Accessibility

Built in:

The field is a spinbutton and the only Tab stop. Screen readers hear the value, the range, and the formatted text ("$1,234.50").
The ▲▼ buttons are hidden from screen readers and skipped by Tab; the arrow keys do the same thing.
The on-screen keyboard shows numbers, without type="number" problems such as the scroll wheel changing the value.
A composing Field names the field, links the help text and error, and marks it invalid on error.

Your part:

Give every number input a name: a Field label, or aria-label.
Set min, max, and step to the real range, and write the range into errors.

Key	Action
`↑` / `↓`	step up or down by `step`
`Shift` + `↑` / `↓`, `Page Up` / `Page Down`	step by `large-step`
`Home` / `End`	go to `min` / `max`, when set
`Enter`	commits the value and submits the form

Contrast limits

The box shares the Input's limits: see Input contrast limits.

Anatomy

Formatting

Value and stepping

Sizes

States

When to use

Content

Do / Don't

Related

API

Attributes

Properties

Slots

Events

Methods

CSS

Tokens

Accessibility

Contrast limits