Generic Structure

Button

A control that performs an action when triggered.

Declaration

struct Button<Label> 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.

Button(action: signIn) {
    Text("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:

Button("Sign In", action: signIn)

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:

// 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: addItem)
}

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

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

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 buttonStyle(_:) modifier:

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

Topics

Creating a Button

init(action: () -> Void, label: () -> Label)

Creates a button that displays a custom label.

init<S>(S, action: () -> Void)

Creates a button that generates its label from a string.

Available when Label is Text.

init(LocalizedStringKey, action: () -> Void)

Creates a button that generates its label from a localized string key.

Available when Label is Text.

init(PrimitiveButtonStyleConfiguration)

Creates a button based on a configuration for a style with a custom appearance and custom interaction behavior.

Available when Label is PrimitiveButtonStyleConfiguration.Label.

Applying Standard Button Styles

struct DefaultButtonStyle

The default button style, based on the button’s context.

struct PlainButtonStyle

A button style that doesn’t style or decorate its content while idle, but may apply a visual effect to indicate the pressed, focused, or enabled state of the button.

struct LinkButtonStyle

A button style for buttons that emulate links.

struct BorderedButtonStyle

A button style that applies standard border artwork based on the button’s context.

struct BorderlessButtonStyle

A button style that doesn’t apply a border.