Contents

Button

A control that initiates an action.

Declaration

struct Button<Label> where Label : View

Mentioned in

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, an icon, or both.

The label of a button can be any kind of view, such as a Text view for text-only labels:

Button(action: signIn) {
    Text("Sign In")
}

Or a Label view, for buttons with both a title and an icon:

Button(action: signIn) {
    Label("Sign In", systemImage: "arrow.up")
}

For those common cases, you can also use the convenience initializers that take a title string or LocalizedStringKey as their first parameter, and optionally a system image name or ImageResource as their second parameter, instead of a trailing closure:

Button("Sign In", systemImage: "arrow.up", action: signIn)

Prefer to use these convenience initializers, or a Label view, when providing both a title and an icon. This allows the button to dynamically adapt its appearance to render its title and icon correctly in containers such as toolbars and menus. For example, on iOS, buttons only display their icons by default when placed in toolbars, but show both a leading title and trailing icon in menus. Defining labels this way also helps with accessibility — for example, applying the labelStyle(_:) modifier with an iconOnly style to the button will cause it to only visually display its icon, but still use its title to describe the button in accessibility modes like VoiceOver:

Button("Sign In", systemImage: "arrow.up", action: signIn)
    .labelStyle(.iconOnly)

Avoid labels that only use images or exclusively visual components without an accessibility label.

How the user activates the button varies by platform:

  • In iOS and watchOS, the user taps the button.

  • In macOS, the user clicks the button.

  • In tvOS, the user presses “select” on an external remote, like the Siri Remote, while focusing on the button.

The appearance of the button depends on factors like where you place it, whether you assign it a role, and how you style it.

Adding buttons to containers

Use buttons for any user interface element that initiates an action. 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 initiates an action when selected by the user, add a button to the list’s content:

List {
    // Cells that show all the current folders.
    ForEach(folders) { folder in
        Text(folder.title)
    }

    // A cell that, when selected, adds a new folder.
    Button(action: addItem) {
        Label("Add Folder", systemImage: "folder.badge.plus")
    }
}

[Image]

Similarly, to create a context menu item that initiates an action, add a button to the contextMenu(_:) modifier’s content closure:

.contextMenu {
    Button("Cut", action: cut)
    Button("Copy", action: copy)
    Button("Paste", action: paste)
}

[Image]

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

Assigning a role

You can optionally initialize a button with a ButtonRole that characterizes the button’s purpose. For example, you can create a destructive button for a deletion action:

 Button("Delete", role: .destructive, action: delete)

The system uses the button’s role to style the button appropriately in every context. For example, a destructive button in a contextual menu appears with a red foreground color:

[Image]

If you don’t specify a role for a button, the system applies an appropriate default appearance.

Styling buttons

You can customize a button’s appearance using one of the standard button styles, like bordered, and apply the style with the buttonStyle(_:) modifier:

HStack {
    Button("Sign In", action: signIn)
    Button("Register", action: register)
}
.buttonStyle(.bordered)

If you apply the style to a container view, as in the example above, all the buttons in the container use the style:

[Image]

You can also create custom styles. 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. Custom styles can also read the button’s role and use it to adjust the button’s appearance.

Topics

Creating a button

Creating a button with a role

Creating a button from a configuration

Creating a button to perform an App Intent

Initializers

See Also

Creating buttons