Buttons

The system offers a range of button styles that support extensive customization while providing built-in interaction states, accessibility support, and appearance adaptation. In addition, there are several system-defined button types — such as toggle, pop-up, and pull-down — that support a variety of specific use cases.

For developer guidance, see UIButton (UIKit) and Button (SwiftUI).

System Buttons

The system defines four button styles, each available in three sizes. Each style has a different level of visual prominence, helping you communicate a hierarchy of actions within your app.

You can configure a system button to use any combination of style and size. By default, a system button uses a size-specific corner radius and your app’s tint color. If necessary, you can change these attributes — in addition to attributes that control content layout and the presence of an activity indicator — in your button configuration. For developer guidance, see UIButton.Configuration.

Create button content that helps people instantly understand what the button does. You can use a glyph (or icon), a title, or both to communicate a button’s purpose. If a glyph makes sense in your button, consider using an existing or customized SF symbol (for guidance, see SF Symbols). To use text, create a short title that succinctly describes what the button does. Use title-style capitalization and a title that starts with a verb to help convey the button’s action — for example, a button that lets people add items to their shopping cart might use the title “Add to Cart.”

Include a subtitle if it provides useful details. A button can display a subtitle below its title. Because the subtitle uses a smaller text size than the title, it works well to communicate secondary information related the button’s action. For example, you might use the subtitle to update an “Add to Cart” button with the number of items in the cart. Avoid using a subtitle to explain more about what the button does; a button’s containing view, title, and image should provide all the information people need to understand its action.

Configure a button to display an activity indicator when you need to provide feedback about an action that doesn’t instantly complete. Displaying an activity indicator within a button can save space in your UI, while clearly communicating the reason for the delay. If it helps clarify what’s happening, you can also configure the button to display a different label alongside the activity indicator. For example, the label “Checkout” could change to “Checking out...” while the activity indicator is visible. When a delay occurs after people tap your configured button, the system displays the activity indicator next to the original or alternative label, hiding the button image, if there is one. For developer guidance, see showsActivityIndicator.

A partial screenshot of the People tab in the Find My app. The People sheet uses two same-sized buttons to provide the option to share their location with another person or cancel. The Share button uses a blue fill with white text and the Cancel button uses a blue outline, no fill, and blue text.

A partial screenshot of the People tab in the Find My app, showing the state that occurs after someone taps the Share button. The Share button keeps the blue fill, but changes the color of the text from white to gray and displays a spinning activity indicator inside the leading edge. The Cancel button continues to use a blue outline and no fill, but changes the color of the text from blue to gray.

Use a filled button for the most likely action in a view. The filled style is the most visually prominent, so it helps people quickly identify the action they’re most likely to want. At the same time, avoid using too many filled buttons in a view. Too many filled buttons can increase cognitive load because people must spend time comparing multiple likely options before making a choice.

Use style — not size — to visually distinguish the preferred choice among multiple options. When you use buttons of the same size to offer two or more options, you signal that the options form a coherent set of choices. If you want to highlight the preferred or most likely option in a set, use a more prominent button style for that option and a less prominent style for the remaining ones.

A partial screenshot of the Maps sheet, showing details about the current location. The sheet displays two same-sized buttons, one labeled Directions and the other labeled Flyover. The Directions button uses a blue fill to indicate that it’s the mostly likely option and the Flyover button uses a gray fill to indicate that it’s a less likely option.

A system button can also have a role, which identifies the button’s semantic meaning within your app. A button can have one of the following roles:

Normal. No specific meaning.
Primary. The button is the default button — that is, the button people are most likely to choose.
Cancel. The button cancels the current action.
Destructive. The button performs an action that can result in data destruction.

A button’s role can have additional effects on the appearance you configure. For example, the system uses bold text for the title in a primary button, whereas a destructive button includes a red color. For developer guidance, see UIButton.Role (UIKit) and role (SwiftUI).

Assign the primary role to the button people are most likely to choose. A primary button should respond to the Return key, making it easy for people to quickly confirm their choice. In addition, when the button is in a temporary view — such as a sheet, an editing view, or an alert — assigning it the primary role means that the view can automatically close when people choose Return.

Don’t assign the primary role to a button that performs a destructive action, even if that action is the most likely choice. Because of its visual prominence, people sometimes choose a primary button without reading it first. Help people avoid losing content by assigning the primary role to nondestructive buttons.

Toggle Buttons

A toggle button is a type of system button that switches between a pair of opposing states, such as on and off or show and hide. To distinguish the states, a toggle button uses two different visual styles. For example, Calendar uses two background appearances for a toggle button that shows and hides the day’s events in the month view.

A screenshot of the Calendar app on iPhone, showing the current month in the top half of the screen and today’s event view in the bottom half.

Calendar displays a solid background shape behind the toggle’s symbol to indicate that the day’s events are visible.

A screenshot of the Calendar app on iPhone, showing a month view that begins with the current month followed by the first two weeks of the next month.

Calendar removes the solid background shape from the toggle to indicate that the day’s events are hidden.

NOTE A toggle button is similar in function to a switch, but you can use a toggle button outside of a list or table row and you don’t need to provide a label that explains its purpose.

For developer guidance, see changesSelectionAsPrimaryAction.

Use a toggle button to help people manage the state of content or a view. In addition to using a toggle button to change the state of something, people expect the button to indicate their current selection. If you need to enable actions other than state management, use a system button or another specific button type, such as a pop-up or pull-down button.

Avoid relying solely on color to communicate a toggle button’s state. By default, a toggle button uses the app’s tint color to show that it’s on, and a different value of the color (or gray) to show that it’s off. If you customize a toggle button, make sure that everyone can perceive visual differences in the button’s state. For example, in addition to using high-contrast color values, you might include other visual changes, such as adding a background shape or varying the button’s content.

Pop-Up Buttons

A pop-up button is a type of system button that can display a menu of mutually exclusive options. After people choose an item from a pop-up button’s menu, the menu closes and the button can update its content to indicate the current selection.

A partial screenshot of the Playlist view in the Music app’s Library tab. The Sort button in the top-right corner of the screen has been tapped, revealing a menu that lists four sorting options. The Playlist Type option is preceded by a checkmark, indicating that it’s the currently selected option.

Music uses a pop-up button to let people choose how to sort their playlists.

For developer guidance, see changesSelectionAsPrimaryAction and showsMenuAsPrimaryAction.

Use a pop-up button to present a flat list of mutually exclusive options or states. A pop-up button helps people make a choice that affects their content or the surrounding view. If you need to offer a list of actions, let people select multiple items, or provide a submenu, use a pull-down button instead.

Display a useful default selection. A closed pop-up button always displays the current selection, but if people haven’t made a selection yet, it displays the default item you specify. When possible, make the default selection an item that most people are likely to want.

Consider using a pop-up button when space is limited and you don’t need to display all options all the time. Although a segmented control also presents a set of mutually exclusive options, it generally requires more space than a pop-up button because it always displays every item.

Pull-Down Buttons

A pull-down button is a type of system button that can display a menu of items or actions that directly relate to the button’s purpose. After people choose an item in a pull-down button’s menu, the menu closes and your app performs the chosen action. People can also close the menu without choosing an item by tapping elsewhere on the screen. Unlike a pop-up button, a pull-down button always displays the same content, regardless of the menu item people choose.

A partial screenshot of the Messages app on iPhone, showing the menu revealed when people tap the Edit button in the top-left corner. The menu lists three actions: Select Messages, Edit Pins, and Edit Name and Photo.

Messages uses a pull-down button to present common editing actions.

NOTE You can also let people reveal a pull-down menu by performing a specific gesture on a button. For example, in iOS 14 and later, Safari responds to a touch and hold gesture on the Tabs button by displaying a menu of tab-related actions, like New Tab and Close All Tabs.

For developer guidance, see showsMenuAsPrimaryAction.

Use a pull-down button to present items that are directly related to the button’s action. The menu lets you help people clarify the button’s target or customize its behavior without requiring additional buttons in your interface. For example:

An add button could present a menu that lets people specify the item they want to add.
A sort button could use a menu to let people select an attribute on which to sort.
A back button could let people choose a specific location to revisit instead of opening the previous one.

Avoid putting all of a view’s actions in one pull-down button. A view’s primary actions need to be easily discoverable, so you don’t want to hide them in a pull-down button. Putting too many actions in a pull-down button makes it less focused and means that people have to tap at least twice to do anything.

Consider using a More pull-down button to present items that don’t need prominent positions in the main interface. A More button can help you offer a range of items where space is constrained, but it can also hinder discoverability. Although people generally understand that a More button offers additional functionality related to the current context, the ellipsis glyph doesn’t help them predict its contents. To design an effective More button, weigh the convenience of its size against its impact on discoverability to find a balance that works in your app. Create a More button by using the ellipsis.circle symbol (see SF Symbols to learn more about symbols).

A screenshot of the Files app on iPhone. In the Browse view, the More button has been selected, which reveals a menu of several actions and options, separated into four groups. In the second group from the top, the Icons option is selected. In the third group from the top, the Size item is selected.

Files uses a More pull-down button to offer actions — like adding a folder or scanning a document — in addition to options for viewing and sorting the content.

Let people know when a pull-down button’s menu item is destructive, and ask them to confirm their intent. Menus use red text to highlight actions that you identify as potentially destructive. When people choose a destructive action, the system displays an action sheet (iOS) or popover (iPadOS) in which they can confirm their choice or cancel the action. Because an action sheet appears in a different location from the menu and requires deliberate dismissal, it can help people avoid losing data by mistake.

Use separators to visually group related items in a pull-down button’s menu. Creating visual groupings can help people scan a menu more quickly. For example, the More button in the Files app uses separators to help people distinguish actions that affect the content from items related to viewing and sorting. Using more than three groups in a menu can make it seem difficult to parse.

Include a glyph with a menu item when it provides value. If you need to clarify an item’s meaning, you can display a glyph or image after its title. Using an SF symbol for this purpose can help you provide a familiar experience while ensuring that the symbol remains aligned with the text at every scale.

Display a succinct menu title if it adds meaning. In general, a pull-down button’s content — combined with descriptive menu items — provides all the context people need, making a menu title unnecessary.

Consider using a submenu if it makes the main menu easier to understand and use. A submenu is a menu item that reveals its own menu when people choose it. After people choose an item in a submenu, the submenu closes, leaving the main menu open. Grouping closely related items into a submenu can shorten the main menu and make it easier to scan, although it requires an additional interaction to access the items. If you need to use a submenu, be sure to give it a title or glyph that clearly identifies its items so people don’t have to open it to find out what it contains.

A screenshot of the Reminders app on iPhone. The More button has been chosen, revealing a menu of items. The Sort By item is preceded with a right-pointing chevron that indicates a hidden submenu.

A screenshot of the Reminders app on iPhone. The More button has been chosen, revealing a menu of items. The Sort By item has been selected, revealing a submenu of sorting options in which the Manual option is selected.

Close Buttons

A close button closes its parent view. Display a close button in the top trailing corner of a sheet or a self-contained view in a collection.

A screenshot of a location sheet in the Maps app, expanded to its full height. In the top-right corner of the sheet is a close button, which looks like a dark gray ex within a light gray disk.

Choosing the close button in a sheet dismisses the sheet.

A screenshot of the Summary tab in the Health app displaying a stack of two separate cards. Both cards display a close button in the top-right corner, which looks like a light gray ex.

Choosing the close button in a view that’s part of a collection removes the view from the collection.

For developer guidance, see UIButton.ButtonType.close.

Within a view, provide either a close button or a done button — don’t provide both. Close and done buttons both dismiss the view, but because they’re not opposite actions, providing both presents a confusing choice. In general, use a done button when people can make changes in the view — in this scenario, you might also want to add a cancel button to let people explicitly discard their changes when they dismiss the view. A close button doesn’t signal that it saves or discards changes, so it works well in a view that people can’t edit, or in a view that people can remove from a set of views.

A screenshot of the Add to Wallet sheet in the Wallet app. The sheet lists three types of cards that people can add to Wallet and includes a close button in the top-right corner.

A close button dismisses the view when people finish interacting with it.

A screenshot of the Library tab in the Music app. The view lists several categories people can use to sort a library, such as playlists and artists. The view displays a button titled Done in the top-right corner.

A done button preserves people’s changes when they dismiss the view.

Provide a close button only when the view doesn’t include a pair of opposing actions that also dismiss it. For example, in a sheet that provides opposing actions like cancel and done, adding a close button is confusing because it’s not clear how it affects the view’s content.

Common Button Types

People instantly recognize several specific button types because these buttons behave consistently throughout the system. For example, an info button always reveals details related to the current context or view.

If you create a button that looks like a common button that people know, ensure that the button behaves as they expect. For example, if you create a button that uses the plus.circle SF symbol, people expect it to let them add an item to the current view. Similarly, using the info.circle symbol in a button identifies it as an info button.

In a list or table row, use an info button only to reveal more information about the row’s content. An info button — called a detail disclosure button when it appears in a list row — doesn’t enable navigation through a hierarchical table or list. If you need to let people drill into a list or table row’s child views, use a disclosure indicator accessory control; see disclosureIndicator(displayed:options:) (list) or disclosureIndicator (table).

A screenshot of the Calendars sheet in the Calendar app. The sheet lists the available calendars and provides buttons to add a calendar or hide all of them. In the top-right corner of the sheet is a button titled Done.

An info button shows details about a list item; it doesn’t enable navigation.

A screenshot of the Settings app. Each setting item includes a right-pointing chevron at the trailing edge of the list, indicating that tapping the list row presents a new view with information about that item.

A disclosure indicator reveals the next level in a hierarchy; it doesn’t show details about the item.