Button

struct · iOS 13.0+ · SDK 27.1

nonisolated struct Button<Label> where Label : View

A control that initiates an action. 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 ``View/labelStyle(_:)`` modifier with an ``LabelStyle/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") } }  Similarly, to create a context menu item that initiates an action, add a button to the ``View/contextMenu(_:)`` modifier's content closure: .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 ``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 ``ButtonRole/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:  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 ``PrimitiveButtonStyle/bordered``, and apply the style with the ``View/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:  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.

Members (0)

This type has no directly callable members in this snapshot. See the framework’s skipped declarations for unsupported APIs.

All SwiftUI types →