跳转至
Structure

Button

A control that performs an action when triggered.

Declaration

struct Button<Label> : View where Label : View

Overview

You create a button by providing an action and a label. The action is either a method or closure property that does something when a user clicks or taps the button. The label is a view that describes the button's action, for example, by showing text such as Cancel or an icon such as a back arrow.

 struct SignInView: View {
     var body: some View {
         Button(action: { /\*sign the user in\*/ }) {
             Text("Sign In")
         }
     }
 }
Button with text reading "Sign in".

For the common case of text-only labels, you can use the convenience initializer that takes a title string (or localized string key) as its first parameter, instead of a trailing closure:

 struct EasySignInView: View {
     var body: some View {
         Button("Sign In", action: { /\*sign the user in\*/ })
     }
 }
Button with text reading "Sign in".

The method of triggering the button varies by platform:

  • In iOS and watchOS, the user triggers a standard button by tapping on it.
  • In macOS, the user triggers a standard button by clicking on it.
  • In tvOS, the user triggers a standard button by pressing "select" on an external remote, like the Siri Remote, while focusing on the button.

Adding Buttons to Containers

Use buttons for any user interface element that triggers actions on press. Buttons automatically adapt their visual style to match the expected style within these different containers and contexts. For example, to create a list cell that triggers an action when selected by the user, add a button to the list's content. For example:

 struct Item: Identifiable {
     let id = UUID()
     let title: String
 }

 struct ListView: View {
     let items = [Item(title: "🍌"), Item(title: "🍑")]
     var body: some View {
         // A list of items, where the last row, when triggered,
         // opens a UI for adding a new item.
         List {
             ForEach(items) { item in
                 Text(item.title)
             }
             Button("Add Item", action: { /\* add item \*/ } )
         }
     }
 }
A list with three items, the last of which is a button reading "Add Item".

Similarly, to create a context menu item that triggers an action, add a button to the menu's content:

 struct ContextMenuView: View {
     var body: some View {
         Text("Press and hold for copy-paste options")
             .contextMenu {
                 Button("Cut", action: { /\* cut \*/ } )
                 Button("Copy", action: { /\* copy \*/ } )
                 Button("Paste", action: { /\* paste \*/ } )
             }
     }
 }
A gif showing a view containing a button reading "Press and hold for copy-past options"; once the button is clicked, a pop-up containing three buttons, reading "Cut," "Copy," and "Paste", appears.

This pattern extends to most other container views in SwiftUI that have customizable, interactive content, like forms (instances of Form).

Styling Buttons

You can customize a button's appearance and interaction behavior. To add a custom appearance with standard interaction behavior, create a style that conforms to the ButtonStyle protocol. To customize both appearance and interaction behavior, create a style that conforms to the PrimitiveButtonStyle protocol. To set a specific style for all button instances within a view, use the View/buttonStyle(_:)-3c92f modifier:

 struct ButtonView: View {
     var body: some View {
         HStack {
             Button("Sign In", action: { /\* sign in \*/ } )
             Button("Register", action: { /\* register \*/ } )
         }
         .buttonStyle(PlainButtonStyle())
     }
 }
A view containing an HStack with two plain text buttons, "Sign In" and "Register".

Availability

iOS 13.0+

macOS 10.15+

tvOS 13.0+

watchOS 6.0+

Topics


Type Alias

Body The type of view representing the body of this view.


Instance Property

body The content and behavior of the view.


Initializer

init(action:label:) Creates a button that displays a custom label.