/widgetkit

name: widgetkit
description: "Implement, review, or improve WidgetKit widgets and controls. Use when building Home Screen, Lock Screen, StandBy, or CarPlay widgets with timeline providers; configurable widgets with AppIntentTimelineProvider; interactive widgets or Control Center controls with Button/Toggle wiring; WidgetKit push reloads, refresh budgets, deep links, Smart Stack relevance, Liquid Glass/accented rendering, widget extension setup, WidgetBundle, App Groups, and entitlements."

WidgetKit

Build home screen widgets, Lock Screen widgets, Control Center controls, and StandBy or CarPlay widget surfaces for iOS 26+.

Keep adjacent-framework guidance scoped to WidgetKit integration. Include ActivityKit and App Intents only where they connect directly to WidgetKit surfaces; hand off full lifecycle, APNs content-state, Siri/Shortcuts/Spotlight, or entity-modeling work to sibling `activitykit` or `app-intents` skills.

See [references/widgetkit-advanced.md](references/widgetkit-advanced.md) for timeline strategies, push-based updates, Xcode setup, and advanced patterns.

Contents

• [Workflow](#workflow)
• [Widget Protocol and WidgetBundle](#widget-protocol-and-widgetbundle)
• [Configuration Types](#configuration-types)
• [TimelineProvider](#timelineprovider)
• [AppIntentTimelineProvider](#appintenttimelineprovider)
• [Widget Families](#widget-families)
• [Interactive Widgets (iOS 17+)](#interactive-widgets-ios-17)
• [ActivityConfiguration Handoff](#activityconfiguration-handoff)
• [Control Center Widgets (iOS 18+)](#control-center-widgets-ios-18)
• [Lock Screen Widgets](#lock-screen-widgets)
• [StandBy Mode](#standby-mode)
• [Widget URL Handling and Deep Links](#widget-url-handling-and-deep-links)
• [Smart Stack Relevance](#smart-stack-relevance)
• [Design Patterns](#design-patterns)
• [iOS 26 Additions](#ios-26-additions)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Workflow

1. Create a new widget

1. Add a Widget Extension target in Xcode (File > New > Target > Widget Extension). 2. Enable App Groups for shared data between the app and widget extension. 3. Define a `TimelineEntry` struct with a `date` property and display data. 4. Implement a `TimelineProvider` (static) or `AppIntentTimelineProvider` (configurable). 5. Build the widget view using SwiftUI, adapting layout per `WidgetFamily`. 6. Declare the `Widget` conforming struct with a configuration and supported families. 7. Register all widgets in a `WidgetBundle` annotated with `@main`.

2. Integrate adjacent surfaces

1. Register an `ActivityConfiguration` in the widget bundle when the app has a Live Activity, but keep `ActivityAttributes`, request/update/end, APNs `content-state`, and Dynamic Island layout depth in `activitykit`. 2. Place `Button`, `Toggle`, `ControlWidgetButton`, and `ControlWidgetToggle` in WidgetKit views or controls, but keep intent modeling, entities, queries, Siri, Shortcuts, and Spotlight in `app-intents`.

3. Add a Control Center control

1. Reuse an `AppIntent`/`OpenIntent` for a button, or a `SetValueIntent` for a toggle. 2. Create a `ControlWidgetButton` or `ControlWidgetToggle` in the widget bundle. 3. Use `StaticControlConfiguration` or `AppIntentControlConfiguration`.

4. Review existing widget code

Run through the Review Checklist at the end of this document.

Widget Protocol and WidgetBundle

Widget

Every widget conforms to the `Widget` protocol and returns a `WidgetConfiguration` from its `body`.

struct OrderStatusWidget: Widget {
    let kind: String = "OrderStatusWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: OrderProvider()) { entry in
            OrderWidgetView(entry: entry)
        }
        .configurationDisplayName("Order Status")
        .description("Track your current order.")
        .supportedFamilies([.systemSmall, .systemMedium])
    }
}

WidgetBundle

Use `WidgetBundle` to expose multiple widgets from a single extension.

@main
struct MyAppWidgets: WidgetBundle {
    var body: some Widget {
        OrderStatusWidget()
        FavoritesWidget()
        DeliveryActivityWidget()   // ActivityConfiguration handoff
        QuickActionControl()       // Control Center
    }
}

Configuration Types

Use `StaticConfiguration` for non-configurable widgets. Use `AppIntentConfiguration` (recommended) for configurable widgets paired with `AppIntentTimelineProvider`.

// Static
StaticConfiguration(kind: "MyWidget", provider: MyProvider()) { entry in
    MyWidgetView(entry: entry)
}
// Configurable
AppIntentConfiguration(kind: "ConfigWidget", intent: SelectCategoryIntent.self,
                       provider: CategoryProvider()) { entry in
    CategoryWidgetView(entry: entry)
}

Shared Modifiers

| Modifier | Purpose | |---|---| | `.configurationDisplayName(_:)` | Name shown in the widget gallery | | `.description(_:)` | Description shown in the widget gallery | | `.supportedFamilies(_:)` | Array of `WidgetFamily` values | | `.supplementalActivityFamilies(_:)` | Live Activity sizes (`.small`, `.medium`) |

TimelineProvider

For static (non-configurable) widgets. Uses completion handlers. Three required methods:

struct WeatherProvider: TimelineProvider {
    typealias Entry = WeatherEntry

    func placeholder(in context: Context) -> WeatherEntry {
        WeatherEntry(date: .now, temperature: 72, condition: "Sunny")
    }

    func getSnapshot(in context: Context, completion: @escaping (WeatherEntry) -> Void) {
        let entry = context.isPreview
            ? placeholder(in: context)
            : WeatherEntry(date: .now, temperature: currentTemp, condition: currentCondition)
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<WeatherEntry>) -> Void) {
        Task {
            let weather = await Weath