ButtonKit

Use AsyncButton for closures that use async/await. The button manages task lifecycle: it prevents duplicate tasks if pressed while a task is already in progress, but remains hittable unless configured otherwise.

Loading State Management:

• .disabledWhenLoading(): Disables the button while the task is running.
• .allowsHitTestingWhenLoading(false): Disables hit testing while the task is running.

Monitoring State:

• .onStateChange: React to .started(task) or .ended(completion).
• .onButtonStateChange: Monitor multiple buttons in a group.
• .onButtonStateCancelled: React to specific button cancellations.

Visual Styles: Use .asyncButtonStyle() to change how the button looks during loading (defaults to a ProgressView replacing the label).

• .overlay (supports .overlay(style: .percent) for deterministic progress)
• .pulse
• .leading
• .trailing
• .symbolEffect(.bounce)
• .none (disables loading animation)

// Basic async usage
AsyncButton {
    try await doSomethingThatTakeTime()
} label {
    Text("Do something")
}
.disabledWhenLoading()

// Monitoring state
AsyncButton {
  ...
} onStateChange: { state in
  switch state {
  case let .started(task):
      // Task started
  case let .ended(completion):
      // Task ended, failed or was cancelled
  }
}

To trigger an AsyncButton from an external source (like a keyboard action) while retaining built-in animations and error handling, you must use a unique id and a triggerButton namespace.

1. Assign a unique id to the AsyncButton.
2. Attach .buttonTriggerNamespace(scope) to the button using a @Namespace.
3. Access the triggerButton environment variable in the calling view to invoke the action.

// 1. Setup the button with an ID and Namespace
enum LoginViewButton: Hashable {
  case login
}

struct ContentView: View {
    @Namespace private var triggerScope

    var body: some View {
        AsyncButton(id: LoginViewButton.login) {
            try await login()
        } label: {
            Text("Login")
        }
        .buttonTriggerNamespace(triggerScope)
    }
}

// 2. Trigger from elsewhere
struct OtherView: View {
    @Environment(\.triggerButton) private var triggerButton
    @Namespace private var triggerScope
    
    func performLogin() {
        triggerButton(id: LoginViewButton.login, in: triggerScope)
    }
}

Use AsyncButton to wrap closures that can throw errors. By default, the button will perform a shake animation when an error is thrown. You can customize this behavior using .throwableButtonStyle().

Available Styles:

• .shake (default)
• .symbolEffect(.wiggle)
• .none (disables error animation)
• Custom styles via the ThrowableButtonStyle protocol.

Monitoring Errors: Use .onButtonStateError on a Group of buttons to monitor failures. If an id is not provided to the AsyncButton, a UUID is generated automatically.

// Basic usage
AsyncButton {
    try doSomethingThatCanFail()
} label {
    Text("Do something")
}

// Monitoring errors in a group
Group {
    AsyncButton(id: "Button 1") {
      ...
    }
    AsyncButton(id: "Button 2") {
      ...
    }
}
.onButtonStateError { event in
    // event.error contains the Swift Error
    // event.buttonID contains the identifier
}

// Customizing error behavior
AsyncButton {
    try doSomethingThatCanFail()
} label {
    Text("Do something")
}
.throwableButtonStyle(.none)

You can report progress within an AsyncButton closure using the progress parameter. This allows AsyncButtonStyle implementations to react to configuration.fractionCompleted.

Available Progress Types:

• .indeterminate: Default non-determinate progress.
• .discrete(totalUnitCount: Int): Linear progress (completed / total).
• .estimated(for: Duration): Fills the bar over a time interval, stopping at 85%.
• .progress: Bridges to (NS)Progress.

Custom Progress: Implement the TaskProgress protocol to create custom logic (e.g., logarithmic progress). TaskProgress.cancel() is called on the main actor when the task is cancelled.

AsyncButton(progress: .discrete(totalUnitCount: files.count)) { progress in
    for file in files {
        try await file.doExpensiveComputation()
        progress.completedUnitCount += 1
    }
} label: {
    Text("Process")
}
.asyncButtonStyle(.trailing) // Responds to progress

Use AsyncButton instead of manual Button { Task { ... } } or do/catch wrappers to handle asynchronous or throwing actions. AsyncButton automatically manages the task lifecycle, provides built-in loading/progress/error feedback, and de-duplicates in-flight actions to prevent multiple simultaneous taps.

Core Workflow:

1. Import the library: import ButtonKit.
2. Replace standard Button actions with AsyncButton { try await ... }.
3. Apply styles for feedback:
   • Use asyncButtonStyle for loading feedback.
   • Use throwableButtonStyle for error feedback.
4. Handle state changes using onButtonStateError or onButtonStateChange.
5. Important: Do not nest a Task inside an AsyncButton action; the component manages the task for you.

import ButtonKit

AsyncButton(action: { try await performAsyncWork() }) {
    Text("Submit")
}
.asyncButtonStyle()
.onButtonStateError { error in
    // Handle error
}