NumberInput

Компонент NumberInput в Chakra UI представляет собой специализированный элемент формы для ввода числовых значений. Он позволяет ограничивать диапазон значений, задавать шаг изменения, поддерживает клавиатурные и кнопочные инкременты/декременты, а также интегрируется с другими компонентами библиотеки.

Базовый синтаксис выглядит следующим образом:

import { NumberInput, NumberInputField, NumberInputStepper, NumberIncrementStepper, NumberDecrementStepper } from '@chakra-ui/react';

<NumberInput defaultValue={10} min={0} max={100} step={5}>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>

Ключевые моменты:

  • defaultValue — начальное значение.
  • min и max — ограничения диапазона.
  • step — величина, на которую изменяется значение при клике на стрелки или использовании клавиатуры.
  • NumberInputField — текстовое поле для ручного ввода.
  • NumberInputStepper с дочерними NumberIncrementStepper и NumberDecrementStepper — визуальные кнопки для увеличения и уменьшения значения.

Контроль состояния и управление значением

Компонент поддерживает контролируемый и неконтролируемый режимы. В контролируемом режиме значение управляется через value и onChange:

function ControlledNumberInput() {
  const [value, setValue] = React.useState(20);

  return (
    <NumberInput value={value} onCha nge={(valueString, valueNumber) => setValue(valueNumber)}>
      <NumberInputField />
      <NumberInputStepper>
        <NumberIncrementStepper />
        <NumberDecrementStepper />
      </NumberInputStepper>
    </NumberInput>
  );
}
  • onChange возвращает два параметра: строковое представление (valueString) и числовое (valueNumber).
  • Это позволяет синхронизировать компонент с внешним состоянием или использовать его в форме с библиотеками вроде Formik или React Hook Form.

Форматирование и парсинг значений

NumberInput поддерживает кастомное форматирование чисел через свойства format и parse. Например, можно добавлять символы валют или проценты:

<NumberInput
  defaultValue={1000}
  min={0}
  max={10000}
  step={100}
  precision={2}
  clampValueOnBlur={true}
>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
  • precision — количество знаков после запятой.
  • clampValueOnBlur — автоматически ограничивает значение при потере фокуса в рамках min и max.

Для более сложного форматирования можно использовать функцию onChange совместно с valueAsNumber или кастомными методами парсинга.

Валидация и ограничения

NumberInput предоставляет встроенные способы ограничения значения:

  • min и max ограничивают диапазон.
  • step задает шаг изменения.
  • isInvalid позволяет визуально выделить некорректное значение.

Пример с валидацией:

<NumberInput
  min={0}
  max={50}
  value={value}
  onCha nge={(val) => setValue(val)}
  isInvalid={value < 0 || value > 50}
>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
  • Цветовая индикация и стили для isInvalid можно кастомизировать через тему Chakra UI.

Кастомизация внешнего вида

Компонент полностью интегрирован с системой стилей Chakra UI, что позволяет изменять все параметры через sx, size, variant, focusBorderColor и другие свойства. Примеры кастомизации:

<NumberInput size="lg" maxW={32} focusBorderColor="teal.400" variant="filled">
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
  • size — определяет размеры поля и кнопок (sm, md, lg).
  • variant — визуальный стиль (outline, filled, flushed, unstyled).
  • focusBorderColor — цвет рамки при фокусе.

Интеграция с клавиатурой и стрелками мыши

NumberInput поддерживает удобное управление через:

  • Стрелки клавиатуры (вверх/вниз) — увеличивают/уменьшают значение на шаг step.
  • Колесо мыши при наведении на поле — также может изменять значение.
  • keepWithinRange — если включено, блокирует выход за пределы min и max при любом способе изменения значения.
<NumberInput defaultValue={10} min={0} max={20} step={2} clampValueOnBlur>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>

Работа с десятичными числами

Для чисел с плавающей запятой важно использовать свойства precision и корректно обрабатывать onChange:

<NumberInput step={0.1} precision={2} min={0} max={10}>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
  • precision={2} гарантирует, что значение будет отображаться с двумя знаками после запятой.
  • Это особенно полезно для финансовых и научных приложений, где точность критична.

Совместная работа с формами

NumberInput легко интегрируется с формами через React Hook Form:

import { useForm, Controller } from 'react-hook-form';

function FormExample() {
  const { control, handleSubmit } = useForm();

  return (
    <form onSub mit={handleSubmit((data) => console.log(data))}>
      <Controller
        name="quantity"
        control={control}
        defaultValue={1}
        render={({ field }) => (
          <NumberInput {...field} min={1} max={100}>
            <NumberInputField />
            <NumberInputStepper>
              <NumberIncrementStepper />
              <NumberDecrementStepper />
            </NumberInputStepper>
          </NumberInput>
        )}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
  • Использование Controller позволяет интегрировать NumberInput в любую форму и отслеживать изменения значения.

События и дополнительные хуки

Компонент поддерживает стандартные события React: onFocus, onBlur, onKeyDown, что позволяет реализовать дополнительные проверки, подсказки и кастомные реакции на действия пользователя.

<NumberInput
  onFo cus={() => console.log('Поле в фокусе')}
  onB lur={() => console.log('Поле потеряло фокус')}
  onKeyD own={(e) => console.log(`Нажата клавиша: ${e.key}`)}
>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
  • Это открывает возможности для динамической валидации, аналитики и адаптивного интерфейса.

Итоговый потенциал NumberInput

Компонент NumberInput является мощным инструментом для создания точных числовых форм в Chakra UI. Он сочетает гибкость, полную кастомизацию внешнего вида и интеграцию с React-экосистемой, включая формы, состояния и обработку событий, что делает его незаменимым при разработке интерактивных и контролируемых интерфейсов.

Оглавление