UIStepper
UIStepper represents a stepper: a minus button and a plus button side by side. Each tap decreases or increases the value by one step. Use it where the user adjusts the current value up or down a little, such as a quantity or a number of people.
A stepper has only the two buttons and does not display the value. Read and write the current value through value; to display it, add a separate UILabel and update it in the change event.
stepValue determines how much each tap changes the value, and minimumValue and maximumValue determine the range. At either end of the range, the button on that side becomes disabled. While the user holds a button down, the value changes continuously.
The system determines the stepper's size; measured on iOS 27.2 it is 94 × 32 pt. With Auto Layout, give it only position constraints.
A stepper is a control: disabling, state, and events come from UIControl.
Inheritance: EventTarget → NSObject → UIResponder → UIView → UIControl → UIStepper
For common patterns, see the guide Building switches, sliders, and steppers.
Constructor
Creates a stepper with a range of 0 to 100 and a step of 1.
Instance properties
Also inherits the properties of UIControl and UIView. The inherited property most often used with steppers is isEnabled.
| Property | Description |
|---|---|
value | The current value |
minimumValue | The lower bound of the range |
maximumValue | The upper bound of the range |
stepValue | How much each tap adds or subtracts |
isContinuous | Whether change fires on every change while the button is held, or only after release |
autorepeat | Whether holding a button keeps adding or subtracting |
wraps | Whether tapping at one end goes around to the other end |
Instance methods
The stepper has no methods of its own. It inherits the methods of UIControl and UIView.
Events
The stepper's events are inherited from UIControl; listen with addEventListener(). The stepper uses:
| Event | When it fires |
|---|---|
change | The user tapped plus or minus and the value changed. Writing value in code does not fire it |
Examples
Choosing a quantity
Starting from a blank app, put a line "Quantity 1" and a stepper on screen, with the quantity between 1 and 10.
application.addEventListener('sceneconnect', (e) => {
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
const label = new UILabel();
label.text = 'Quantity 1';
// Set the range first, then the value
const stepper = new UIStepper();
stepper.minimumValue = 1;
stepper.maximumValue = 10;
stepper.value = 1;
stepper.addEventListener('change', () => {
label.text = 'Quantity ' + stepper.value;
});
const row = new UIStackView([label, stepper]);
row.spacing = 12;
row.alignment = 'center';
row.translatesAutoresizingMaskIntoConstraints = false;
page.view.addSubview(row);
const safe = page.view.safeAreaLayoutGuide;
NSLayoutConstraint.activateConstraints([
row.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 24 }),
row.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 16 }),
]);
});Effect (not verified in the simulator)
- "Quantity 1" appears near the top left of the screen, with a stepper with minus and plus buttons to its right. The minus button is gray.
- Tapping plus changes the text to "Quantity 2", and the minus button becomes enabled.
- Holding plus down increases the number continuously until it stops at "Quantity 10", and the plus button turns gray.
Corresponding iOS API
| ObjC | JS |
|---|---|
[[UIStepper alloc] init] | new UIStepper() |
stepper.value = 5 | stepper.value = 5 |
stepper.stepValue = 0.5 | stepper.stepValue = 0.5 |
stepper.continuous = NO | stepper.isContinuous = false |
stepper.wraps = YES | stepper.wraps = true |
[stepper addTarget:self action:@selector(changed:) forControlEvents:UIControlEventValueChanged] | stepper.addEventListener('change', fn) |
Comparison with the browser
| Browser | Nacre |
|---|---|
<input type="number" min max step>, with a text box and up/down arrows | new UIStepper() has only the two buttons and no text box; display the value yourself |
input.stepUp(), input.stepDown() | No corresponding methods. Write stepper.value += stepper.stepValue yourself |
See also
- Building switches, sliders, and steppers: steps of 0.5, wrapping, handling only after release
UIControl:isEnabledand all control eventsUILabel: displaying the current valueUISlider: use a slider when the range is large and exact steps are not needed