---
title: Stepper
description: >-
The `Stepper` component provides increment and decrement controls for numeric
values with visual feedback. Use it to adjust quantities, counts, or other
numeric values with clear visual buttons.
The component provides visual increment and decrement controls with
customizable step values and min/max constraints to control numeric
adjustments. It supports both button clicks and keyboard input for
flexibility, with visual feedback for boundary conditions and disabled states
to prevent invalid value entries during quantity adjustments or numeric
configurations.
`Stepper` components provide continuous increment behavior when buttons are
held down, enabling rapid value changes while still supporting single-step
precision adjustments for fine-tuned control.
api_version: 2024-07
api_name: pos-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/pos-ui-extensions/2024-07/ui-components/forms/stepper
md: >-
https://shopify.dev/docs/api/pos-ui-extensions/2024-07/ui-components/forms/stepper.md
---
# Stepper
The `Stepper` component provides increment and decrement controls for numeric values with visual feedback. Use it to adjust quantities, counts, or other numeric values with clear visual buttons.
The component provides visual increment and decrement controls with customizable step values and min/max constraints to control numeric adjustments. It supports both button clicks and keyboard input for flexibility, with visual feedback for boundary conditions and disabled states to prevent invalid value entries during quantity adjustments or numeric configurations.
`Stepper` components provide continuous increment behavior when buttons are held down, enabling rapid value changes while still supporting single-step precision adjustments for fine-tuned control.
## Properties
Configure the following properties on the `Stepper` component.
* initialValue
number
required
The initial value of the stepper that sets the starting numeric value when the component is first rendered.
* onValueChanged
(value: number) => void
required
A callback function executed when the value of the stepper changes, receiving the new numeric value as a parameter.
* disabled
boolean
Default: false
Whether the field can be modified, disabling both increment and decrement buttons.
* maximumValue
number
The maximum value that the stepper can reach. When the value equals the maximum, the increment button will be disabled.
* minimumValue
number
Default: 1
The minimum value that the stepper can reach. When the value equals the minimum, the decrement button will be disabled.
* value
number
An optional value to override the internal state of the component. Only use this if you need complete control over the stepper's value from external state.
### Examples
* #### Increment and decrement a number
##### Description
Provide increment and decrement buttons for numeric input with visual feedback. This example demonstrates a Stepper that allows merchants to adjust quantities, counts, or values using clear visual controls with customizable step values and min/max constraints.
##### React
```tsx
import React, { useState } from 'react';
import { Screen, reactExtension, Text, Stepper, ScrollView } from '@shopify/ui-extensions-react/point-of-sale';
const SmartGridModal = () => {
const [value, setValue] = useState(4);
return (
{value}
);
}
export default reactExtension('pos.home.modal.render', () => {
return
})
```
##### TS
```ts
import {
extension,
Screen,
ScrollView,
Stepper,
Text,
} from '@shopify/ui-extensions/point-of-sale';
export default extension(
'pos.home.modal.render',
(root) => {
const mainScreen = root.createComponent(
Screen,
{name: 'stepper', title: 'Stepper'},
);
const scrollView =
root.createComponent(ScrollView);
const text = root.createComponent(
Text,
null,
'4',
);
const stepper = root.createComponent(
Stepper,
{
initialValue: 4,
onValueChanged: (value) => {
text.replaceChildren(value.toString());
},
},
);
scrollView.append(stepper);
scrollView.append(text);
mainScreen.append(scrollView);
root.append(mainScreen);
},
);
```
## Preview
## Best practices
* **Use initialValue for default starting points:** Set `initialValue` to a sensible default that makes sense for your use case, such as 1 for quantities or a typical value for settings.
* **Let the component manage its own state:** By default, `Stepper` manages its own internal state—you only need to respond to `onValueChanged` to capture the new value. Avoid using the `value` property unless you specifically need to override the internal state for external synchronization.
* **Handle value changes appropriately:** Implement the `onValueChanged` callback to capture value changes and update your application state, trigger calculations, or perform related actions based on the new numeric value.
* **Provide visual context for stepper values:** While `Stepper` handles the increment/decrement controls, consider displaying the current value prominently alongside the `Stepper` buttons so users can see the exact numeric value, not just the controls.
* **Design for touch interaction:** `Stepper` buttons are optimized for touch interaction on POS devices. Ensure adequate spacing around the `Stepper` buttons and consider the overall layout to prevent accidental taps on adjacent controls.
## Limitations
* `Stepper` provides increment/decrement controls only—if users need to enter specific values directly by keyboard, combine `Stepper` with a `NumberField` component.
* The component manages integer values by default—fractional or decimal increments require using the optional `value` property with external state management.
* `Stepper` doesn't include labels or field descriptions—combine with `Text` components or other UI elements to provide context about what value is being adjusted.