Пропсы корня
| Проп | Тип | По умолчанию |
|---|---|---|
value | number | — |
Контролируемое значение. NaN означает, что поле пустое. | ||
defaultValue | number | NaN |
Начальное значение для неконтролируемого использования. По умолчанию NaN — пустое поле. | ||
onChangeValue | (value: number) => void | — |
Вызывается с числом при его изменении и с NaN, когда поле очищено. | ||
step | number | 1 |
| Шаг, на который значение увеличивается или уменьшается клавишами со стрелками или кнопками счётчика. | ||
min | number | Number.MIN_SAFE_INTEGER |
| Минимально допустимое значение поля. Соблюдается и через HTML-атрибуты, и во внутренней логике. | ||
max | number | Number.MAX_SAFE_INTEGER |
| Максимально допустимое значение поля. | ||
ref | Ref<HTMLDivElement> | — |
| Ref, передаваемый на элемент. | ||
precision | number | 0 |
| Количество знаков после запятой, до которого округляется значение. Полезно для финансовой или научной точности. | ||
changeOnWheel | boolean | true |
| Включает изменение значения колесом мыши, когда поле в фокусе. | ||
allowEmpty | boolean | true |
| Позволяет полю быть пустым (null/undefined) вместо значения 0 по умолчанию. Полезно для необязательных числовых полей. | ||
maximumFractionDigits | number | 2 |
Максимальное количество цифр после десятичного разделителя. Управляет точностью числа, когда значение вводится или меняется действиями увеличения/уменьшения. Обычно используется для денежных сумм, измерений или рейтингов, где дробную точность нужно ограничить. Пример: maximumFractionDigits={0} → только целые числа; maximumFractionDigits={2} → до двух знаков после запятой | ||
disabled | boolean | — |
| Отключает весь NumberField. | ||
size | TextFieldSize | 'md' |
| Визуальный размер текстового поля. Влияет на отступы, размер шрифта и общую высоту. 'sm': компактное поле; 'md': по умолчанию; 'lg': просторная раскладка | ||
error | boolean | — |
| Показывает поле ввода в состоянии ошибки. | ||
Также принимает все атрибуты <div>.
Дочерние части
NumberFieldInput: числовой input, связанный с контекстом.NumberFieldIncrementButton: кнопка увеличения.NumberFieldDecrementButton: кнопка уменьшения.
NumberFieldDecrementButton
| Проп | Тип | По умолчанию |
|---|---|---|
size | IconButtonSize | — |
| Размер контейнера кнопки. Управляет отступами и общей кликабельной областью. | ||
asChild | boolean | — |
Если true, рендерит кнопку как дочерний компонент через Slot (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег. | ||
variant | ButtonBaseVariant | — |
| Определяет визуальный стиль кнопки: цветовую схему и акцент. | ||
appearance | ButtonBaseAppearance | — |
| Настраивает структурный внешний вид кнопки (фон, рамка и т. д.). | ||
disabled | boolean | — |
Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с asChild: отключённым состоянием владеет дочерний элемент, например через aria-disabled или ссылку без href. | ||
className | string | — |
| Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей. | ||
children | ReactNode | — |
| Содержимое кнопки — текст, иконка или любой React-узел. | ||
ref | Ref<HTMLButtonElement> | — |
Ref, передаваемый на нативный элемент <button>. Даёт прямой доступ к DOM для управления фокусом или измерений. | ||
Также принимает все атрибуты <button>.
NumberFieldIncrementButton
| Проп | Тип | По умолчанию |
|---|---|---|
size | IconButtonSize | — |
| Размер контейнера кнопки. Управляет отступами и общей кликабельной областью. | ||
asChild | boolean | — |
Если true, рендерит кнопку как дочерний компонент через Slot (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег. | ||
variant | ButtonBaseVariant | — |
| Определяет визуальный стиль кнопки: цветовую схему и акцент. | ||
appearance | ButtonBaseAppearance | — |
| Настраивает структурный внешний вид кнопки (фон, рамка и т. д.). | ||
disabled | boolean | — |
Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с asChild: отключённым состоянием владеет дочерний элемент, например через aria-disabled или ссылку без href. | ||
className | string | — |
| Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей. | ||
children | ReactNode | — |
| Содержимое кнопки — текст, иконка или любой React-узел. | ||
ref | Ref<HTMLButtonElement> | — |
Ref, передаваемый на нативный элемент <button>. Даёт прямой доступ к DOM для управления фокусом или измерений. | ||
Также принимает все атрибуты <button>.
NumberFieldInput
| Проп | Тип | По умолчанию |
|---|---|---|
ref | Ref<HTMLInputElement> | — |
Ref, передаваемый на нижележащий нативный элемент <input>. | ||
Также принимает все атрибуты <input>.
Типы
NumberFieldPropsNumberFieldInputPropsNumberFieldIncrementPropsNumberFieldDecrementPropsNumberFieldSize
Модель состояния
- Корень отслеживает, находится ли текущее значение на min или max.
- Стрелки и, если включены, события колеса меняют значение на шаг через логику корня. Как и в
<input type="number">, колесо меняет только поле в фокусе; без фокуса оно прокручивает страницу. - Шаг сохраняет десятичные знаки значения и
step(0.7+0.1даёт0.8). onKeyDownкорня выполняется после встроенной обработки стрелок и не заменяет её.- Корень принимает
value,defaultValueиonChangeValueкак число,NaN— для пустого поля;NumberFieldInputпоказывает отформатированный текст и по-прежнему вызывает собственныеonChangeиonInput. Сброс формы восстанавливаетdefaultValue, если поле не контролируемое.