Intro

The step input component allows users to adjust numeric values in predefined increments (steps) using either buttons or direct input. It’s particularly useful when users need to quickly change values like quantities or measurements without manually typing every number. The component supports both keyboard and mouse interactions, and it can be customized with minimum, maximum, and step values.

Step input

When to Use

false

Use the step input when:

Users need to adjust amounts, quantities, or other numeric values quickly.
Users need to change values in defined increments (for example, in a shopping cart).

dont

false

Do not use the step input if:

Users need to enter a fixed number (for example, a postal code, phone number, or ID). Use a regular input field instead.
Users need to enter a value that rarely changes or doesn’t follow defined steps (for example, a fixed account number). Use a regular input field instead.
Users need to enter dates or times. Use a date picker, date range selection, time picker, or date/time picker instead.

Anatomy

Decrease button: Decreases the current value by one step.
Input field: Displays the current value and allows direct numeric input.
Increase button: Increases the current value by one step.

Anatomy of the step input component

Types

The value in the input field can be:

A. Left-aligned: Aligns numbers to the left within the input field.

B. Centered: Centers the value in the input field.

C. Right-aligned (default): Aligns numbers to the right, which is recommended for comparing numeric values.

D. Step input with description: Displays descriptive text alongside the component (for example, currency or units of measure).

Е. Step input with a label: Uses a label to identify the component (for example, price or quantity in a shopping cart).

To make it easier to compare numeric values, use right alignment.

Types of the step input component

States

Interaction States

The step input has four basic interaction states:

A. Hover: Appearance when the pointer is over the component.

B. Active: Appearance while the component is being clicked or tapped.

C. Disabled: Appearance when the component is inactive and cannot be used.

D. Read only: Appearance when the value is fixed and cannot be changed.

Interaction states of the step input component

Interaction States – Increase and Decrease Buttons

The increase and decrease buttons have two interaction states:

A. Hover: Appearance when the cursor is over the button or the component area.

B. Active: Appearance when a button is being clicked.

Increase and decrease buttons states of the step input component

Value States

The step input component offers the four value states listed below. For the error, warning, and information states, you can show an additional value state text when the focus is on the input field. If the text gets too long, it wraps.

A. Negative: Indicates an error or invalid entry.

B. Critical: Highlights a value that needs attention.

C. Positive: Confirms a successful or valid entry.

D. Information: Provides additional details without indicating an error or warning.

For more information on how to use the different value states, see How to Use Semantic Colors.

For more information on showing value states in a form, see Form Field Validation.

Value states of the step input component

Behavior and Interaction

Default Value

The step input always contains a value. When no value is set, the default value is generally 0. However, app developers can set a different default value.

If the minimum value is larger than 0, the generic value is the minimum value set by the app team.

Changing the Value

Users can adjust the value in several ways:

By pressing the increase or decrease buttons
By typing a number directly into the field
By using keyboard shortcuts (Up/Down arrows, Page Up/Page Down)
By scrolling with the mouse wheel

On desktop, clicking inside the field places the cursor in the input. On mobile, tapping the field opens the numeric keyboard.

The buttons change the value in steps without moving the caret into the field.

If the field is cleared and focus is lost, the value resets to 0, or to the minimum if that is greater than 0.

When an invalid value is entered, it remains visible in the field and an error state is shown.

Increasing the Step

To let users change values in larger steps using keyboard shortcuts, app developers can define a multiple of the step with the (property: largerStep). By default, this is set to two times the standard step.

For more advanced step behavior (for example, ensuring the increment always lands on the nearest number divisible by the defined step), you can use the (property: stepMode) property. See API reference for more information.

Maximum and Minimum Values

The step input can be configured with minimum and maximum values to control the valid range of inputs.

When the maximum value is reached, the increase button and related keyboard navigation (for example, the up arrow) are disabled, while the decrease button remains active. Conversely, when the minimum value is reached, the decrease button and down arrow are disabled.

Step input component at maximum and minimum values (max = 100, min = -100)

Display Value

The step input component allows decimal values and can control the number of digits shown after the decimal point (property: displayValuePrecision). When the property is set to a specific value – from 0 (default) to 20 – the component restricts users accordingly as they type or paste a value. Trying to type more digits triggers an error state.

Guidelines

Use clear, meaningful labels for the step input that align with the context of the form or the conversation with users, to help them understand the purpose of the value they are adjusting. Labels are especially useful when several step inputs are displayed together, such as in forms or tables, to ensure users can easily distinguish each field’s purpose.

Width

By default, the step input takes up 100% of its container. Instead of setting a fixed width, embed the component in a suitable layout (such as a form, simple form, or grid layout) and use the layout data property with the 12-column responsive grid to define behavior for sizes S, M, and L. In forms, the width is influenced by the label-to-field ratio, but developers can restrict it to the appropriate number of columns to avoid overly wide inputs.

When used in forms, the width of the step input control comes from the label:field ratio of the form. The app development team should be able to restrict the width to a proper number of columns (12-grid responsive layout) so that the step input is not too wide.

Always ensure the width fits the expected range of values without being larger than necessary. Consider varying decimal lengths and, where possible, limit the number of digits after the decimal point. For details on numeric formatting, see the article on formatting numbers.

Localization

The step input supports both left-to-right (LTR) and right-to-left (RTL) layouts. In LTR mode, the decrease button appears on the left, followed by the numeric value, and the increase button is on the right. In RTL mode, the increase button appears on the left, followed by the numeric value, and the decrease button is on the right.