SuperAPI AI Directory

widgetkit

General & other

View repository

Updated 10-16 05:53

About this skill

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

Surface Supported Families Configuration Key API
Home Screen .systemSmall, .systemMedium, .systemLarge, .systemExtraLarge AppIntentConfiguration containerBackground(for:)
Lock Screen .accessoryCircular, .accessoryRectangular, .accessoryInline StaticConfiguration Monochrome / accented styling
StandBy .systemSmall, .systemMedium Same as Home Screen Night mode / red tint adaptation
Control Center ControlWidget (buttons & toggles) StaticControlConfiguration ControlWidgetButton, ControlWidgetToggle

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

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