Skip to content

UISwitch ​

UISwitch represents a switch: a round thumb on a short track, off when the thumb is on the left and on when it is on the right. The user taps it or drags the thumb to toggle it. It is used where something has only two values and takes effect immediately when toggled, such as "whether to enable an option".

Read and write the switch's state through isOn. After the user toggles it, the switch fires the change event; writing isOn in code doesn't fire it.

The switch's size is decided by the system; writing the width and height of frame has no effect. The switch has no text of its own; use a UILabel for the description next to it and put the two together in a horizontal UIStackView.

A switch is a control: disabling, state, and events come from UIControl. A control is in turn a view: position and background color come from UIView.

Inheritance: EventTarget → NSObject → UIResponder → UIView → UIControl → UISwitch

For how to make a settings item with a switch, see the guide Building switches, sliders, and steppers.

Constructor ​

UISwitch()

Creates a switch that is off.

Instance properties ​

Also inherits the properties of UIControl and UIView. The inherited property most often used on a switch is isEnabled.

PropertyDescription
isOnWhether it is on or off
onTintColorThe color of the track when it is on
thumbTintColorThe color of the thumb

Instance methods ​

Also inherits the methods of UIControl and UIView.

MethodDescription
setOn()Toggles the switch, optionally animated

Events ​

The switch's events are inherited from UIControl; listen with addEventListener(). The one a switch uses is:

EventWhen it fires
changeThe user toggles the switch to the other side. Writing isOn or calling setOn() in code doesn't fire it

Examples ​

A settings row ​

Starting from a blank app, put a "Notifications" row with a switch on screen.

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 = 'Notifications';

  const sw = new UISwitch();
  sw.isOn = true;
  sw.addEventListener('change', () => {
    console.log('notifications', sw.isOn ? 'on' : 'off');
  });

  const row = new UIStackView([label, sw]);
  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)

  • "Notifications" appears near the top left of the screen, with a green switch that is on to its right.
  • Tap the switch: the thumb slides to the left, the track turns gray, and the console prints notifications off.
  • Tap it again, and the console prints notifications on.

safeAreaLayoutGuide is the area of the view controller not covered by the notch and rounded corners; see Auto Layout.

Corresponding iOS API ​

ObjCJS
[[UISwitch alloc] init]new UISwitch()
sw.on / sw.isOnsw.isOn
[sw setOn:YES animated:YES]sw.setOn(true, { animated: true })
sw.onTintColor = UIColor.systemPurpleColorsw.onTintColor = 'systemPurple'
[sw addTarget:self action:@selector(changed:) forControlEvents:UIControlEventValueChanged]sw.addEventListener('change', fn)

See also ​