Skip to content

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 ​

UIStepper()

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.

PropertyDescription
valueThe current value
minimumValueThe lower bound of the range
maximumValueThe upper bound of the range
stepValueHow much each tap adds or subtracts
isContinuousWhether change fires on every change while the button is held, or only after release
autorepeatWhether holding a button keeps adding or subtracting
wrapsWhether 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:

EventWhen it fires
changeThe 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.

js
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 ​

ObjCJS
[[UIStepper alloc] init]new UIStepper()
stepper.value = 5stepper.value = 5
stepper.stepValue = 0.5stepper.stepValue = 0.5
stepper.continuous = NOstepper.isContinuous = false
stepper.wraps = YESstepper.wraps = true
[stepper addTarget:self action:@selector(changed:) forControlEvents:UIControlEventValueChanged]stepper.addEventListener('change', fn)

Comparison with the browser ​

BrowserNacre
<input type="number" min max step>, with a text box and up/down arrowsnew 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 ​