SwiftUI Button: Styles, Roles & Custom ButtonStyle

The anatomy of a SwiftUI Button

Every Button is two things: an action that runs on tap, and a label that describes it. The most common form uses a string convenience initializer, but you can pass any view as the label — an Image, an HStack of icon plus text, or a fully composed layout. Because the label is just a view, buttons compose exactly like the rest of SwiftUI. Prefer the trailing-closure action form for readability, and keep the action short; heavy work belongs in a view model, not inline in the closure.

// String label
Button("Save") { save() }

// Explicit action + label view
Button(action: save) {
    Label("Save", systemImage: "tray.and.arrow.down")
}

// Icon-only, with an accessibility label
Button {
    save()
} label: {
    Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share")

Built-in button styles

SwiftUI ships several styles you apply with .buttonStyle. Reach for .borderedProminent for the primary call to action on a screen, .bordered for secondary actions, and .plain when you want the label to render with no chrome at all. You can also set .controlSize and .tint to fine-tune sizing and color without writing a custom style. Applying a style to a container propagates it to every button inside, so you rarely repeat yourself.

• .borderedProminent — filled, high-emphasis primary action
• .bordered — tinted capsule for secondary actions
• .plain — no background, useful inside lists and toolbars
• .tint(.red) and .controlSize(.large) refine any style

VStack(spacing: 12) {
    Button("Continue") { advance() }
        .buttonStyle(.borderedProminent)
        .controlSize(.large)

    Button("Maybe later") { dismiss() }
        .buttonStyle(.bordered)

    Button("Skip") { skip() }
        .buttonStyle(.plain)
}
.tint(.indigo)

Roles: destructive and cancel

A button role tells SwiftUI the semantic meaning of the action so it can style and place it correctly. Button(role: .destructive) renders red inside menus and confirmation dialogs, and .cancel gets special treatment in dialogs and alerts. Roles are not just cosmetic — VoiceOver announces them, and confirmationDialog uses them to order and emphasize choices. Use them instead of hardcoding a red tint on a delete button.

struct DeleteRow: View {
    @State private var confirming = false

    var body: some View {
        Button("Delete Account", role: .destructive) {
            confirming = true
        }
        .confirmationDialog("Delete this account?",
                            isPresented: $confirming,
                            titleVisibility: .visible) {
            Button("Delete", role: .destructive) { deleteAccount() }
            Button("Cancel", role: .cancel) { }
        }
    }
}

Custom buttons with the ButtonStyle protocol

When the built-in styles are not enough, conform a struct to ButtonStyle. Its makeBody(configuration:) receives a configuration whose label is your button's content and whose isPressed flag drives press feedback. This is the correct place to add scale-on-press animation, gradients, or shadows — it keeps interaction state out of your view and makes the style reusable across the whole app. Avoid re-implementing tap handling with gestures; ButtonStyle already gives you accessibility and hit-testing for free.

struct CapsuleButtonStyle: ButtonStyle {
    func makeBody(configuration: Configuration) -> some View {
        configuration.label
            .font(.headline)
            .padding(.vertical, 12)
            .padding(.horizontal, 24)
            .background(Color.accentColor, in: Capsule())
            .foregroundStyle(.white)
            .scaleEffect(configuration.isPressed ? 0.96 : 1)
            .opacity(configuration.isPressed ? 0.85 : 1)
            .animation(.easeOut(duration: 0.15), value: configuration.isPressed)
    }
}

// Usage
Button("Get Started") { start() }
    .buttonStyle(CapsuleButtonStyle())

Async actions, disabled state, and iOS 26 Liquid Glass

A button action is synchronous, but you often want to await work. Wrap the call in a Task and drive a loading flag so you can disable the button and show a ProgressView while it runs. Use .disabled(_:) to gate the button on validation, and it will dim and stop responding automatically. On iOS 26, Apple introduced Liquid Glass — apply .buttonStyle(.glass) for a system glass button, or wrap custom content in .glassEffect() to float it above scrolling content. Gate glass code behind an availability check so iOS 16–25 users fall back gracefully.

struct SubmitButton: View {
    @State private var isLoading = false
    let isValid: Bool

    var body: some View {
        Button {
            Task {
                isLoading = true
                defer { isLoading = false }
                try? await submit()
            }
        } label: {
            if isLoading { ProgressView() } else { Text("Submit") }
        }
        .disabled(!isValid || isLoading)
        .modifier(GlassIfAvailable())
    }
}

struct GlassIfAvailable: ViewModifier {
    func body(content: Content) -> some View {
        if #available(iOS 26, *) {
            content.buttonStyle(.glass)
        } else {
            content.buttonStyle(.borderedProminent)
        }
    }
}

How to build a custom primary button in SwiftUI

Create a reusable, on-brand primary button you can drop anywhere in your app.

1. 1

   Define the ButtonStyle

   Create a struct conforming to ButtonStyle and implement makeBody(configuration:).

   struct PrimaryButtonStyle: ButtonStyle { /* ... */ }

2. 2

   Read isPressed

   Use configuration.isPressed to add a scale or opacity change for tactile feedback.

   .scaleEffect(configuration.isPressed ? 0.97 : 1)

3. 3

   Apply and reuse

   Attach it with .buttonStyle(PrimaryButtonStyle()) on any Button in the app.

   Button("Save") { save() }.buttonStyle(PrimaryButtonStyle())

Frequently Asked Questions