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 increase or decrease 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

Label slot

Label via Prop

Placeholder

Step

Fraction Digits

Tooltip

Tooltip Position

Top Center

Show Help Text

Use Range

Disabled

Required

Info Icon

Label

        
          
            <
            NumericStepper

            





            
                label
              
                =
                "Label"
              

                step
              
                =
                "0.01"
              

                fractionDigits
              
                =
                "2"
              

                range
              
                =
                "[
  0,
  150
]"
              

                placeholder
              
                =
                "1000"
              

                helpText
              
                =
                "Help Text"
              

                validation
              
                =
                "info"
              

                tooltipPosition
              
                =
                "top-center"
              

                useHelpTextIcon
              



  />

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.

States

The Numeric Stepper has two levels of interactive states:
Stepper control states apply to the component as a whole, including its outer container and editable value field.
Button states apply independently to the increase and decrease buttons.
Stepper control states: Default, Hover, Focus, Focus Visible, Locked.
Increase and decrease button states: Default, Hover, Pressed, Focus Visible, Locked.
Focus is applied when the editable value field is focused using a mouse or pointer.
Focus Visible is applied when the value field or one of the buttons receives keyboard focus, for example through the Tab key.
In both the Focus and Focus Visible states of the value field, a text caret appears to indicate that the value can be edited.
The Locked state disables the entire Numeric Stepper, including both buttons and the editable value field.
The Invalid and Valid validation states can only have Default and Hover states. When the user clicks on an Invalid or Valid Numeric Stepper, the validation is cleared and the component transitions to the Focus state. Pressing Tab instead transitions it to the Focus Visible state.

Variants

Input

Placeholder or value input.

FormLabel

Show or hide Form Label.

HelpText

Show or hide Help Text.

Help Text + Validation

Show or hide Help Text.
The Numeric Stepper supports three validation states: None, Invalid, and Valid. When validation is applied, the Help Text communicates the current validation result.
If the Numeric Stepper has informational Help Text and a validation state is triggered, the validation message replaces the original informational message. Validation feedback always takes priority over informational Help Text.
Depending on the use case, validation may be triggered after the user submits the form or moves focus away from the Numeric Stepper after changing its value.

Properties

export type NumericStepperProps = Omit<NumberInputProps, 'modelValue' | 'unit' | 'labelCategory'> & {
  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;
}

ModelValues

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

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

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 ​