Button

A control that initiates an action when pressed.

Overview

Buttons are one of the most common UI elements. They trigger actions when tapped, like submitting forms, navigating to another screen, or performing operations.

Basic Usage

Button {
    print("Button pressed!")
} child: {
    Text("Click Me")
}

The first closure is the action handler, the child: closure is the button content.

import Foundation
import JavaScriptKit
import Observation
import Shaft
import ShaftWeb

Shaft.backend = ShaftWebBackend { _ in
    JSObject.global.document.querySelector("canvas")
}

@Observable class ButtonDemoState {
    var clickCount = 0
    var lastRole: String = "primary"
}

let state = ButtonDemoState()

runApp(ButtonDemoApp())

final class ButtonDemoApp: StatelessWidget {
    func build(context: any BuildContext) -> any Widget {
        Column(mainAxisAlignment: .center, spacing: 24) {
            Text("Button Demo")
                .textStyle(.init(fontSize: 24, fontWeight: .bold))

            Text("Clicked \(state.clickCount) times (\(state.lastRole))")
                .textStyle(.init(color: Color(0xFF_666666)))

            // Primary Button
            Button(role: .primary) {
                state.clickCount += 1
                state.lastRole = "primary"
            } child: {
                Text("Primary Button")
            }

            // Secondary Button
            Button(role: .secondary) {
                state.clickCount += 1
                state.lastRole = "secondary"
            } child: {
                Text("Secondary Button")
            }

            // Destructive Button
            Button(role: .destructive) {
                state.clickCount += 1
                state.lastRole = "destructive"
            } child: {
                Text("Delete")
            }

            // Disabled Button
            Button(role: .primary, onPressed: nil) {
                Text("Disabled")
            }

            // Button with Icon
            Row(spacing: 8) {
                Button(
                    icon: Text("→"),
                    role: .primary
                ) {
                    state.clickCount += 1
                    state.lastRole = "with icon"
                } child: {
                    Text("Next")
                }
            }
        }
        .padding(.all(40))
    }
}

Button Roles

Buttons can have different roles that affect their appearance:

// Primary (default) - Main actions
Button(role: .primary) {
    // action
} child: {
    Text("Save")
}

// Secondary - Less prominent actions
Button(role: .secondary) {
    // action
} child: {
    Text("Cancel")
}

// Destructive - Dangerous actions
Button(role: .destructive) {
    // action
} child: {
    Text("Delete")
}

// Cancel - Cancel operations
Button(role: .cancel) {
    // action
} child: {
    Text("Cancel")
}

// Link - Acts like a hyperlink
Button(role: .link) {
    // action
} child: {
    Text("Learn More")
}

Disabled State

Pass nil for onPressed to disable the button:

Button(onPressed: nil) {
    Text("Disabled")
}

With Icon

Add an icon next to the button label:

Button(
    icon: Text("→"),  // or use ShaftLucide icons
    role: .primary
) {
    print("Next")
} child: {
    Text("Next")
}

Selected State

Buttons can show a selected state:

Button(isSelected: true) {
    // action
} child: {
    Text("Selected")
}

Useful for toggle buttons or tab-like interfaces.

Custom Styling

Create custom button styles by conforming to Button.Style:

struct CustomButtonStyle: Button.Style {
    func build(context: any Button.StyleContext) -> any Widget {
        context.child
            .textStyle(.init(color: Color(0xFF_FFFFFF)))
            .padding(.all(16))
            .decoration(.box(
                color: context.isPressed 
                    ? Color(0xFF_FF6B6B)
                    : Color(0xFF_FF8787),
                borderRadius: .circular(8)
            ))
    }
}

// Apply to a button
Button { } child: { Text("Custom") }
    .buttonStyle(CustomButtonStyle())

// Apply to all descendant buttons
Column {
    Button { } child: { Text("Button 1") }
    Button { } child: { Text("Button 2") }
}
.buttonStyle(CustomButtonStyle())

Control Size

Adjust button size using ControlSize:

Column {
    Button { } child: { Text("Mini") }
    Button { } child: { Text("Small") }
    Button { } child: { Text("Regular") }
    Button { } child: { Text("Large") }
}
.controlSize(.mini)   // or .small, .regular, .large

Parameters

See Also

• TextField - Text input widget
• Text - Display text
• State Management - Managing button state