WidgetKit

Build glanceable Home Screen widgets, Lock Screen complications, Control Center controls, and StandBy or CarPlay widgets using WidgetKit. Targets Swift 6.3 / iOS 26+.

Contents

• Extension Architecture
• Widget Families and Surfaces
• Timeline Management and Reload Budgets
• Interactive Controls and Intent Handoff
• Route by Task
• Common Mistakes
• Review Checklist
• References

Extension Architecture

1. Separate extension target: Widgets run in an out-of-process widget extension.
2. Shared storage with App Groups: Use UserDefaults(suiteName: "group.com.example.app") or shared container directories to share data between the main app and the widget.
3. Widget Bundle: Group all widgets, live activities, and controls in a single @main WidgetBundle.

@main
struct AppWidgetsBundle: WidgetBundle {
    var body: some Widget {
        OrderStatusWidget()
        QuickActionControl()
    }
}

Widget Families and Surfaces

Timeline Management and Reload Budgets

Timelines provide entries into the future:

• .atEnd: Requests a new timeline after the last entry date passes.
• .after(Date): Schedules a reload at a specific future timestamp.
• .never: Never reloads automatically; relies on app foreground reloads or push notifications.

[!IMPORTANT] The system enforces a daily reload budget (typically 40-70 reloads per day). Do not schedule sub-minute reloads with .after. For urgent real-time state, push remote updates via push-notifications or use activitykit Live Activities.

Interactive Controls and Intent Handoff

Widgets support interactive buttons and toggles:

• Use Button(intent:) and Toggle(isOn:intent:) conforming to AppIntent.
• Route detailed intent modeling and parameter resolution to app-intents.
• Route Dynamic Island and Lock Screen real-time progress to activitykit.

Route by Task

• For timeline provider setups, deep link handling (widgetURL), and configurable intents, read Timelines, Configuration, and Deep Links.
• For Live Activity registration in widget bundles and push-to-update tokens, read Live Activity Presentation and Push.
• For memory budget limits, container backgrounds, and relevance entries for Smart Stacks, read Performance, Setup, and Lifecycle.

Common Mistakes

• Performing network requests or expensive computations inside the SwiftUI widget view instead of the TimelineProvider.
• Hardcoding views without .containerBackground(for: .widget), breaking iOS 17+ StandBy and Lock Screen rendering.
• Scheduling timeline reloads every few seconds, rapidly exhausting the daily reload budget.
• Forgetting App Group entitlement when reading data stored by the main app.
• Attempting to display videos, web views, or complex continuous animations in widget views.

Review Checklist

• App Group configured on both app and widget extension targets
• Timeline entries include future dates with appropriate reload policy (.atEnd, .after)
• Widget views support all declared supportedFamilies
• .containerBackground applied to all widget content views
• Accessory families designed for high-contrast, monochrome display
• Interactive controls trigger AppIntent without launching the main app unnecessarily
• Daily reload budget respected; urgent changes pushed via APNs

References

• Timelines, configuration, and deep links
• Live Activity presentation and push
• Performance, setup, and lifecycle
• WidgetKit documentation
• Widget
• TimelineProvider