Number input

Number input принимает число, которое вводят с клавиатуры: сумму, цену, ставку, размер. Поле умеет показывать значение как валюту, проценты или единицы измерения, а маленькие кнопки ▲▼ меняют его на шаг. Чтобы у поля была подпись, оберните его в Field.

Стабильный

Figma

Обзор

Использование

API

Доступность

<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>

Анатомия

Часть	Что это
`tk-number-input`	сам элемент; одна остановка Tab
part `field`	рамка поля
part `input`	внутреннее текстовое поле с ролью spinbutton
слоты `prefix` / `suffix`	текст или иконка до или после значения, по желанию
part `spinners`	пара ▲▼ у правого края; нажмите, чтобы сделать шаг, или удерживайте

Подпись, подсказку и сообщение об ошибке рисует Field.

Форматирование

<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>

Без фокуса поле показывает отформатированное значение («$1,234.50»), а в фокусе — простое число («1234.5»), чтобы разделители не мешали печатать. value всегда остаётся простым числом.
format: decimal (по умолчанию), currency с кодом в currency (без него — USD), percent или unit с единицей в unit, например kilometer. precision фиксирует число знаков после запятой, locale задаёт разделители.
format="percent" считает значение долей: 0.5 показывается как «50%». Если ваше значение уже 50, поставьте суффикс %.
Префикс и суффикс — украшение, скринридеры их не читают. Если единица — часть значения, берите format.
Для остальных возможностей Intl.NumberFormat задайте свойство formatOptions. Оно перекрывает атрибуты-сокращения.

Значение и шаг

min, max и step задают допустимые значения. Ввести можно что угодно; когда человек уходит из поля, жмёт Enter или делает шаг, значение прижимается к диапазону и округляется до step.
▲▼ и стрелки меняют значение на step. Page Up, Page Down и Shift со стрелкой — на large-step (десятая часть диапазона или step × 10, если диапазона нет).
На min или max соответствующая кнопка отключается. Шаг из пустого поля начинается с min или с 0.
Отрицательные числа вводить можно, если min не задан или меньше 0.
Колесо мыши значение не меняет. Чтобы разрешить, задайте wheel: тогда колесо работает, только пока поле в фокусе.

Размеры

<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`	Высота	Отступ слева	Текст значения
`medium` (по умолчанию)	32px	`space-8`	Body Small (14/20)
`large`	36px	`space-10`	Body Medium (16/24)

Высоты совпадают с кнопками medium и large. Размера small нет: с size="small" поле рисуется как medium и пишет предупреждение в консоль.

Состояния

<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>

Рамка ведёт себя как у Input: при наведении не меняется, а при фокусе окрашивается в цвет фокуса и утолщается внутрь. Кнопки ▲▼ под курсором подсвечиваются.

readonly: на поле можно перейти и скопировать значение, но не изменить. Кнопки ▲▼ скрыты.
disabled: на поле нельзя перейти и нельзя его изменить, а в форму оно не попадает.
Ошибка: задайте error у Field. Поле прижимает значение к диапазону, но само ошибку не показывает: когда и что сказать, решаете вы.
Обязательное поле: задайте required у Field. Без Field ставьте его на сам number input.

Когда использовать

Если значение —	Берите
число, которое вводят: дроби, деньги, проценты, единицы, большой или открытый диапазон	Number input
небольшое целое, которое меняют кнопками − и +: количество, число гостей	Number stepper
значение на шкале, которое задают перетаскиванием	Slider
цифры, которые не количество: индекс, номер карты или счёта	Input с `inputmode="numeric"`
одноразовый код	OTP input

Текст

Правила для подписи, подсказки и ошибки те же, что у Input. В ошибке про диапазон называйте диапазон: «Введите число мест от 1 до 500».

Можно / нельзя

✅ Можно	❌ Нельзя
Брать Number input для количеств	Брать его для индексов, номеров карт и телефонов
Хранить числовое `value`	Хранить отформатированный текст
Задавать `min`, `max` и `step` по реальному диапазону	Оставлять ограниченное значение без границ
Ставить суффикс `%`, если значение уже 50	Ставить `format="percent"`: он покажет 50 как 5000%
Оставлять колесо выключенным	Включать `wheel` в длинной прокручиваемой форме

Field: подпись, подсказка и ошибка вокруг поля.
Number stepper: кнопки − и + для небольших целых чисел.
Slider: значение задают перетаскиванием.
Input: ввод текста и путь для цифр, которые не количество.

API

Атрибуты

Атрибут	Тип	По умолчанию	Что делает
`value`	number \| null	`null`	число; `null`, если пусто; отправляется под именем `name`
`name`	string	—	имя поля в форме
`min`	number	—	наименьшее значение; без него нижней границы нет
`max`	number	—	наибольшее значение; без него верхней границы нет
`step`	number	`1`	шаг стрелок и ▲▼ и сетка, к которой округляется значение
`large-step`	number	—	шаг для Page Up / Page Down и Shift
`format`	`decimal` \| `currency` \| `percent` \| `unit`	`decimal`	как показывать значение без фокуса
`currency`	string	—	код ISO 4217 для `format="currency"`; без него `USD`
`unit`	string	—	единица для `format="unit"`, например `kilometer`
`precision`	number	—	фиксированное число знаков после запятой
`locale`	string	—	локаль для разделителей, например `de-DE`
`wheel`	boolean	`false`	разрешает менять значение колесом, пока поле в фокусе
`placeholder`	string	—	подсказка внутри пустого поля; лучше без неё
`inputmode`	string	`decimal` или `numeric`	экранная клавиатура; `numeric`, когда подходят только целые
`autocomplete`	string	—	назначение для автозаполнения, например `transaction-amount`
`required`	boolean	`false`	браузер не отправит форму с пустым полем
`readonly`	boolean	`false`	можно перейти и скопировать, нельзя изменить; ▲▼ скрыты
`disabled`	boolean	`false`	не в фокусе, не редактируется, не попадает в форму
`size`	`medium` \| `large`	`medium`	высота 32 / 36px

Свойства

formatOptions: объект Intl.NumberFormatOptions; перекрывает format, currency, unit и precision.

Слоты

Слот	Содержимое
`prefix`	текст или один `tk-icon` перед значением, например `$`
`suffix`	текст или один `tk-icon` после значения, например `%` или `kg`

События

Событие	Когда
`input`	при каждом изменении и каждом шаге
`change`	когда значение подтверждено: при уходе из поля, по Enter и на каждом шаге

Если удерживать ▲▼, пара событий приходит на каждый повтор. Текущее значение — в свойстве value.

Методы

focus(): переводит фокус в поле.

CSS

::part(field): рамка поля.
::part(input): внутреннее текстовое поле.
::part(spinners): пара ▲▼.

Токены

Во всех состояниях рамка использует токены Input. Кнопки ▲▼:

Роль	Покой	Наведение	Нажатие	Отключено
глиф	`icon/default`	`icon/default`	`icon/default`	`icon/disabled`
фон	нет	`state/hover`	`state/press`	нет

Каждая кнопка — капсула radius-full, на space-4 от правого края рамки. Префикс и суффикс — text/secondary. Значения по темам: Color.

Доступность

Встроено:

Поле — это spinbutton и единственная остановка Tab. Скринридер сообщает значение, диапазон и отформатированный текст («$1,234.50»).
Кнопки ▲▼ скрыты от скринридеров и пропускаются при Tab; то же самое делают стрелки.
Экранная клавиатура цифровая, но без проблем type="number", например смены значения колесом.
Field вокруг поля называет его, связывает с ним подсказку и ошибку и при ошибке отмечает поле как неверное.

На вашей стороне:

Дайте каждому полю имя: подпись в Field или aria-label.
Задайте min, max и step по реальному диапазону и называйте диапазон в ошибках.

Клавиша	Действие
`↑` / `↓`	шаг вверх или вниз на `step`
`Shift` + `↑` / `↓`, `Page Up` / `Page Down`	шаг на `large-step`
`Home` / `End`	к `min` / `max`, если они заданы
`Enter`	подтверждает значение и отправляет форму

Пределы контраста

Пределы те же, что у Input: см. пределы контраста Input.

Анатомия

Форматирование

Значение и шаг

Размеры

Состояния

Когда использовать

Текст

Можно / нельзя

Связанные

API

Атрибуты

Свойства

Слоты

События

Методы

CSS

Токены

Доступность

Пределы контраста