UISegmentedControl
UISegmentedControl represents a segmented control: a horizontal row of segments, each showing a title or an image, with at most one segment selected at a time. Use it to switch between two to five parallel options, such as "Day / Week / Month" or "All / Unread".
Segments are referred to by index, starting at 0. Read and write the selected segment through selectedSegmentIndex. When the user taps a different segment, the control fires a change event. Changing the selected segment from code does not fire change.
A newly created control has no selected segment, and selectedSegmentIndex is -1. Reading or writing a segment's content with an out-of-range index throws TypeError; it is not ignored.
The control's width is computed from its content. You can also give it a larger width with constraints or frame, and the segments share it equally. The height is set by the system; measured on iOS 27.2, it is 32 pt.
A segmented control is a control: enabling, state, and events come from UIControl. A control is also a view: position, size, and background color come from UIView.
Inheritance: EventTarget → NSObject → UIResponder → UIView → UIControl → UISegmentedControl
For how to build common designs with it, see the guide Building segmented controls and page indicators.
Constructor
Creates a segmented control from an array of titles and images, one segment per item.
Instance properties
Also inherits properties from UIControl and UIView. The inherited properties most often used with a segmented control are isEnabled and translatesAutoresizingMaskIntoConstraints.
| Property | Description |
|---|---|
numberOfSegments read-only | The number of segments |
selectedSegmentIndex | The index of the selected segment. -1 means none is selected |
isMomentary | Whether a segment stays selected after a tap; turn this on to use the control as a row of buttons |
apportionsSegmentWidthsByContent | Whether segment widths follow their content or are equal |
selectedSegmentTintColor | The color of the highlight behind the selected segment |
Instance methods
Also inherits methods from UIControl and UIView.
Adding and removing segments:
| Method | Description |
|---|---|
insertSegmentWithTitle() | Inserts a title segment |
insertSegmentWithImage() | Inserts an image segment |
removeSegmentAtIndex() | Removes one segment |
removeAllSegments() | Removes all segments |
Setting a segment's content, with the index in { forSegmentAtIndex }:
| Method | Description |
|---|---|
setTitle() | Sets the segment's title |
setImage() | Sets the segment's image |
setWidth() | Sets the segment's width |
setContentOffset() | Nudges the title or image inside the segment |
setEnabled() | Disables or enables just this segment |
Reading a segment's content:
| Method | Description |
|---|---|
titleForSegmentAtIndex() | The segment's title |
imageForSegmentAtIndex() | The segment's image |
widthForSegmentAtIndex() | The segment's width |
contentOffsetForSegmentAtIndex() | The offset of the content inside the segment |
isEnabledForSegmentAtIndex() | Whether the segment can be tapped |
Events
All events are inherited from UIControl; listen with addEventListener(). A segmented control uses:
| Event | When it fires |
|---|---|
change | The user tapped a segment and the selected segment changed. When isMomentary is true, it fires on every tap |
Examples
Day / Week / Month
Starting from a blank app, put a "Day / Week / Month" segmented control on screen, with a label below that shows which segment is selected.
application.addEventListener('sceneconnect', (e) => {
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
const titles = ['Day', 'Week', 'Month'];
const seg = new UISegmentedControl(titles);
seg.selectedSegmentIndex = 0;
const label = new UILabel();
label.text = 'Showing Day view';
seg.addEventListener('change', () => {
label.text = 'Showing ' + titles[seg.selectedSegmentIndex] + ' view';
});
const column = new UIStackView([seg, label]);
column.axis = 'vertical';
column.spacing = 12;
column.translatesAutoresizingMaskIntoConstraints = false;
page.view.addSubview(column);
const safe = page.view.safeAreaLayoutGuide;
NSLayoutConstraint.activateConstraints([
column.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 24 }),
column.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 16 }),
column.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -16 }),
]);
});Effect (not verified in the simulator)
- A segmented control spans the top of the screen. The three segments are equal in width, and "Day" looks selected. Below it is "Showing Day view".
- Tap "Week": the selection highlight slides to "Week", and the text changes to "Showing Week view".
- Tap the already selected "Week" again: nothing happens.
safeAreaLayoutGuide is the area of the view controller that is not covered by the notch or the rounded corners; see Auto Layout.
For more patterns, see the guide Building segmented controls and page indicators.
Corresponding iOS API
| ObjC | JS |
|---|---|
[[UISegmentedControl alloc] initWithItems:@[@"Day", @"Week"]] | new UISegmentedControl(['Day', 'Week']) |
seg.selectedSegmentIndex = UISegmentedControlNoSegment | seg.selectedSegmentIndex = -1 |
seg.momentary = YES | seg.isMomentary = true |
[seg insertSegmentWithTitle:@"Year" atIndex:3 animated:YES] | seg.insertSegmentWithTitle('Year', { atIndex: 3, animated: true }) |
[seg removeSegmentAtIndex:0 animated:NO] | seg.removeSegmentAtIndex(0) |
[seg setTitle:@"This week" forSegmentAtIndex:1] | seg.setTitle('This week', { forSegmentAtIndex: 1 }) |
[seg titleForSegmentAtIndex:1] | seg.titleForSegmentAtIndex(1) |
[seg setEnabled:NO forSegmentAtIndex:2] | seg.setEnabled(false, { forSegmentAtIndex: 2 }) |
[seg setContentOffset:CGSizeMake(0, 2) forSegmentAtIndex:0] | seg.setContentOffset({ width: 0, height: 2 }, { forSegmentAtIndex: 0 }) |
[seg addTarget:self action:@selector(changed:) forControlEvents:UIControlEventValueChanged] | seg.addEventListener('change', changed) |
Two differences from native:
- Natively, some methods throw on an out-of-range index and others silently do nothing; here they all throw
TypeError. - Natively, after the selected segment is removed,
selectedSegmentIndexreads -2; here it is -1.
See also
- Building segmented controls and page indicators: icon segments, clearing the selection, adding and removing segments, using the control as buttons
UIControl:isEnabledand all control eventsUIImage: getting SF Symbols and your own images- Colors: how to write color strings
UITabBarController: to switch between several full screens, use a tab bar instead of a segmented control