Declaration
Initializers
9 SwiftUI initializers back <Button>. The props you pass pick one.
<Button
onPress: () => void
>
children?: ReactNode
</Button>@preconcurrency nonisolated init(
action: @escaping @MainActor () -> Void,
@ContentBuilder label: () -> Label
)onPress*() => voidThe action to perform when the user triggers the button.
Swift
action: () -> VoidchildrenReactNodeContent. Strings become
Text; React Native views are laid out by Yoga and placed by SwiftUI.Swift
label: () -> Label
Also takes the common view props: modifiers, style and testID.
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 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.
From Apple’s SwiftUI documentation. Code samples there are Swift.
Relationships
Conforms to
- View
See also
More in Controls.
- ColorPickerA control used to select a color from the system color picker UI.
- DatePickerA control for selecting an absolute date.
- DisclosureGroupA view that shows or hides another content view, based on the state of a disclosure control.
- MultiDatePickerA control for picking multiple dates.
- OutlineGroupA structure that computes views and disclosure groups on demand from an underlying collection of tree-structured, identified data.
- PasteButtonA system button that reads items from the pasteboard and delivers it to a closure.
- PickerA control for selecting from a set of mutually exclusive values.
- SecureFieldA control into which people securely enter private text.
- SliderA control for selecting a value from a bounded linear range of values.
- StepperA control that performs increment and decrement actions.
- SubscriptionViewA view that subscribes to a publisher with an action.
- TableA container that presents rows of data arranged in one or more columns, optionally providing the ability to select one or more members.