Size S and M (Smartphone and Tablet)

On smartphones and tablets, the step input is shown in cozy mode. When the focus is in the input field, the keyboard layout for numeric input is displayed.

Size L (Desktop)

On desktop devices, the step input is shown in compact mode.

For more information on the cozy and compact modes, see content density.

The step input consists of an input field and buttons with icons to decrease or increase the value.

You can show a descriptive reference or unit of measurement after the field (property: description). Depending on your use case, you may need to adjust how the space is distributed between the input field and the descriptive text (property: fieldWidth).

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 (property: value).

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

Changing the Value

The user changes the value:

• By pressing the increase/decrease buttons
• By typing a number
• With keyboard shortcuts (up/down, page up/down)
• With the mouse scroll wheel

On desktop devices, clicking the input field places the cursor in the input field. On mobile devices, tapping the input field displays the numeric keyboard.

Clicking the buttons changes the value by a step and does not place the caret in the input field.

When the user clears the value and leaves the input field, the value in the field becomes 0 or the minimum if the minimum is larger than 0.

If the user enters an invalid value, the invalid value remains in the input field. An error state is displayed.

Increasing the Step

To allow the user to change values by a larger step with keyboard shortcuts, app developers can set a multiple of the step (property: largerStep). The default value is two times the set step.

If your use case requires more complex step increments (for example, if you want the step increment to be the closest number that is divisible by the defined step) you can use the stepMode property. For details, please refer to the API reference.

Maximum and Minimum Values

App developers can set a maximum and minimum value for the step input.

When the maximum/minimum values are reached, the Increase/Decrease button and up/down keyboard navigation are disabled.

Display Value

The step input control 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 control restricts users accordingly as they type or paste a value. Trying to type more digits triggers an error state.

Always provide a meaningful label for the step input.

Width

By default the width of the step input is set to 100% of the container. Avoid setting a fixed width, but rather embed the control in a proper layout such as a form, simple form, or grid layout, and use the layout data property where the width is defined by the 12-column approach to define the responsive behavior for sizes S, M, and L.

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.

Ensure an appropriate width for the range of values to be entered for all the sizes S, M, and L. Avoid a larger width than necessary.

Keep in mind the varying lengths of decimals. Limit the number of digits after the floating point if possible in your use case. For more information, have a look at the article on formatting numbers.

Value States

The step input control offers the four value states listed below. For the error and warning states, you can show an additional value state text when the focus is on the input field.

• None (default): No value state message is shown
• Warning
• Error
• Success: No value state message is shown

For more guidance on when to use which state, see message handling. For more information on showing value states in a form, see form field validation.

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

The step input control is enabled and editable by default. Set the control to editable to allow the user to enter a value.

Not Editable

Property settings: editable = false, enabled = true

Use this state, for example, to display data only.

Disabled

Property settings: editable = not relevant, enabled = false

Set the control to disabled in an edit scenario to indicate that the user cannot change the control, for example, due to missing access rights or previous conditions not having been fulfilled or selected.