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.

Anatomy

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

Playground

Label slot

Label via Prop

Label Size

Placeholder

Step

Fraction Digits

Show Help Text

Use Range

Disabled

Required

Tooltip

Tooltip Position

Label

        
          
            <
            NumericStepper

            





            
                label
              
                =
                "Label"
              

                labelCategory
              
                =
                "large"
              

                labelPosition
              
                =
                "labelAbove"
              

                step
              
                =
                "0.01"
              

                fractionDigits
              
                =
                "2"
              

                range
              
                =
                "[
  0,
  150
]"
              

                placeholder
              
                =
                "1000"
              

                helpText
              
                =
                "Help Text"
              

                validation
              
                =
                "info"
              

                tooltipPosition
              
                =
                "top-center"
              



  />

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 behaviour (Default, Hover, Active - button only, Focus, Locked).

Variants

Input

Placeholder or value input.

Form Label

Show or hide.

Help Text

Show or hide.

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.

NumericStepper ​

Anatomy ​