FieldStepper

Числовое поле для выбора значения шагами через кнопки − / + и/или прямой ввод. Базируется на FieldDecorator поверх <input type="number"> без нативных стрелочек. Кнопки − и + — buttonField-слоты по краям поля, отделённые от значения вертикальными разделителями; фон (acrylic) общий для кнопок и инпута.

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

• Количество товара в корзине, кол-во гостей, штучные параметры.
• Числовые настройки с понятным шагом (вес, объём, время в минутах).
• Когда дискретные значения уместнее ползунка Slider (есть осмысленный «один тик»).

Анатомия

Size (default m)

ValidationState (default default)

Через проп error форсится error.

Кнопки −/+

Кнопки шага — buttonField-слоты по краям поля, а не отдельные элементы вне инпута.

• − — слот слева, отделён от значения вертикальным Divider.
• + — слот справа, отделён от значения вертикальным Divider.

Кнопки не участвуют в табуляции (tabIndex={-1}) — фокус принимает сам инпут. Фон (acrylic) общий для кнопок, разделителей и инпута: на hover/focus подсвечивается единым слоем.

Поведение

Тултипы

• minusButtonTooltip / plusButtonTooltip — TooltipProps для подсказки над соответствующей кнопкой шага.
• clampTooltipText — тексты тултипа клампа. Показывается на 2 секунды после blur, когда вручную введённое значение вышло за min (clampTooltipText.min(value)) или max (clampTooltipText.max(value)) при allowMoreThanLimits={false}. По умолчанию — Значение должно быть больше либо равно {value} для нижней границы и Значение должно быть меньше либо равно {value} для верхней.

Установка

pnpm add @cloud-ru/ds-fields

import { FieldStepper } from '@cloud-ru/ds-fields'

Controlled vs uncontrolled

FieldStepper работает в двух режимах:

• Controlled — передаётся value + onChange. Состояние держит потребитель, компонент только отображает текущее значение.
• Uncontrolled — передаётся defaultValue (или ничего; тогда начальное значение выводится из min/max). Компонент держит состояние внутри, onChange остаётся опциональным для наблюдения.

Не смешивайте режимы: либо value, либо defaultValue.

Примеры использования

Базовый stepper

import { FieldStepper } from '@cloud-ru/ds-fields';
import { useState } from 'react';

export function Stepper() {
  const [value, setValue] = useState(1);
  return <FieldStepper label='Количество' value={value} onChange={setValue} />;
}

Uncontrolled

import { FieldStepper } from '@cloud-ru/ds-fields';

export function StepperUncontrolled() {
  return <FieldStepper label='Количество' postfix='шт' defaultValue={3} min={0} max={10} />;
}

С единицей измерения

import { FieldStepper } from '@cloud-ru/ds-fields';
import { useState } from 'react';

export function StepperWithPostfix() {
  const [value, setValue] = useState(12);
  return <FieldStepper label='Количество' postfix='шт' value={value} onChange={setValue} />;
}

Min/Max с клампом

import { FieldStepper } from '@cloud-ru/ds-fields';
import { useState } from 'react';

export function StepperLimits() {
  const [value, setValue] = useState(0);
  return (
    <FieldStepper
      label='Возраст'
      hint='От 0 до 120'
      min={0}
      max={120}
      allowMoreThanLimits={false}
      value={value}
      onChange={setValue}
    />
  );
}

Дробный шаг

import { FieldStepper } from '@cloud-ru/ds-fields';
import { useState } from 'react';

export function StepperFractional() {
  const [value, setValue] = useState(1.5);
  return <FieldStepper label='Вес' postfix='кг' step={0.5} min={0} max={20} value={value} onChange={setValue} />;
}

Тултипы кнопок и клампа

import { FieldStepper } from '@cloud-ru/ds-fields';
import { useState } from 'react';

export function StepperTooltips() {
  const [value, setValue] = useState(3);
  return (
    <FieldStepper
      label='Количество'
      hint='Наведите на кнопки −/+; превышение границ показывает тултип на blur'
      min={0}
      max={10}
      allowMoreThanLimits={false}
      value={value}
      onChange={setValue}
      minusButtonTooltip={{ tip: 'Уменьшить' }}
      plusButtonTooltip={{ tip: 'Увеличить' }}
      clampTooltipText={{
        min: limit => `Не меньше ${limit}`,
        max: limit => `Не больше ${limit}`,
      }}
    />
  );
}

Props

Types

FieldStepperProps

FieldLayoutPresets

Related props

FieldLength

QuestionTooltipProps

Size

TooltipProps

ValidationState

Storybook

Figma