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.

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

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

init(PrimitiveButtonStyleConfiguration)

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

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.

Applying Custom Button Styles

protocol ButtonStyle

A type that applies standard interaction behavior and a custom appearance to all buttons within a view hierarchy.

protocol PrimitiveButtonStyle

A type that applies custom interaction behavior and a custom appearance to all buttons within a view hierarchy.

Styling Buttons

func buttonStyle<S>(S) -> View

Sets the style for buttons within this view to a button style with a custom appearance and standard interaction behavior.

func buttonStyle<S>(S) -> View

Sets the style for buttons within this view to a button style with a custom appearance and custom interaction behavior.

Applying Standard Modifiers

View Modifiers

Configure this view and the views it contains by applying standard modifiers.

Relationships

Conforms To

See Also

Buttons

struct NavigationLink

A button that triggers a navigation presentation when pressed.

struct MenuButton

A button that displays a menu containing a list of choices when pressed.

struct EditButton

A button that toggles the edit mode for the current edit scope.

struct PasteButton

A system button that triggers reading data from the pasteboard.