NumericStepper

Molecule

The Numeric Stepper Component is a form input component used to select or adjust numeric values in a controlled and precise way. It is best suited for scenarios where users need to increment or decrement values by a defined step, such as dimensions, quantities, or configuration parameters. Use this component when numeric accuracy matters and when limiting the input to valid numeric ranges helps prevent user errors.

Playground

ModelValues

For more information on ModelValues please have a look to the Vue's Data Binding section.

const modelValue = defineModel<NumericStepperProps['modelValue']>({ required: true });

Properties

export type NumericStepperProps = Omit<NumberInputProps, 'modelValue' | 'unit'> & {
  modelValue: number | null;
};

export type FormLabelCategory = "compact" | "default";
export type FormLabelPosition = "labelLeading" | "labelTrailing" | "labelAbove";

export interface FormLabelProps extends TooltipProps {
  label?: string;
  tooltip?: string;
  labelCategory: FormLabelCategory;
  labelPosition: FormLabelPosition,
  disabled?: boolean;
  required?: boolean;
  clickableLabel?: boolean;
}

export type TooltipPosition = 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center';

export interface TooltipProps {
  tooltip?: string;
  tooltipPosition?: TooltipPosition;
  tooltipLines?: number;
}

Developer Notes

NOTE

Blur Event (@blur): Triggered when the input is unfocused.
Keydown Event (@keydown): Triggered when any key from the keyboard is pressed while component is focused.

Functionality

Once a NumericStepper element is in :active state, you can use your keyboard to manipulate the input, too.

• Arrow up: increase input by 1 * step
• Arrow down: decrease input by 1 * step
• Ctrl + Arrow *: increase/decrease by 10 * step
• Ctrl + Shift + Arrow *: increase/decrease by 100 * step

You can also specify ranges for the allowed input values. When inputting values out of bounds, an invalid help text will be displayed, indicating the corresponding overflow.

Tokens

SCSS Variable

Value

$numeric-stepper-icon-color

--bds-brand-primary-color

$numeric-stepper-inputNumber-color--locked

--color-grey-70

$numeric-stepper-icon-color--locked

--color-grey-70

$NumericStepper-text: %numbers

Anatomy

1. Form label (optional) - Describes the purpose of the numeric value.
2. Container – Wraps all elements of the Numeric Stepper and defines spacing, alignment, and overall layout.
3. Decrease button - Lowers the value by a defined step.
4. Value field - Displays the current numeric value and allows manual input (if enabled).
5. Increase button - Raises the value by a defined step.
6. Help text (optional) - Provides additional guidance, context, or constraints for the input.

States

The Numeric Stepper supports interactive states applied both to the entire component and to the increase and decrease buttons to ensure clear user feedback and consistent behavior (Default, Hover, Active - button only, Focus, Locked).

Variants

Input

Placeholder or value input

Form Label

Show or hide

Help Text

Show or hide