axiom-extensions-widgets-ref

Extensions & Widgets API Reference

Overview

This skill provides comprehensive API reference for Apple's widget and extension ecosystem:

• Standard Widgets (iOS 14+) — Home Screen, Lock Screen, StandBy widgets
• Interactive Widgets (iOS 17+) — Buttons and toggles with App Intents
• Live Activities (iOS 16.1+) — Real-time updates on Lock Screen and Dynamic Island
• Control Center Widgets (iOS 18+) — System-wide quick controls
• Liquid Glass Widgets (iOS 26+) — Accented rendering, glass effects, container backgrounds
• visionOS Widgets (visionOS 2+) — Mounting styles, textures, proximity awareness
• App Extensions — Shared data, lifecycle, entitlements

Widgets are SwiftUI archived snapshots rendered on a timeline by the system. Extensions are sandboxed executables bundled with your app.

When to Use This Skill

✅ Use this skill when:

• Implementing any type of widget (Home Screen, Lock Screen, StandBy)
• Creating Live Activities for ongoing events
• Building Control Center controls
• Sharing data between app and extensions
• Understanding widget timelines and refresh policies
• Integrating widgets with App Intents
• Adopting Liquid Glass rendering in widgets
• Supporting watchOS or visionOS widgets
• Implementing visionOS mounting styles, textures, or proximity awareness

❌ Do NOT use this skill for:

• Pure App Intents questions (use app-intents-ref skill)
• SwiftUI layout issues (use swiftui-layout skill)
• Performance optimization (use swiftui-performance skill)
• Debugging crashes (use xcode-debugging skill)

Related Skills

• app-intents-ref — App Intents for interactive widgets and configuration
• swift-concurrency — Async/await patterns for widget data loading
• swiftui-performance — Optimizing widget rendering
• swiftui-layout — Complex widget layouts
• extensions-widgets — Discipline skill with anti-patterns and debugging

Key Terminology

• Timeline — Series of entries defining when/what content to display; system shows entries at specified times
• TimelineProvider — Protocol supplying timeline entries (placeholder, snapshot, timeline generation)
• TimelineEntry — Struct with widget data + display date
• Timeline Budget — Daily limit (40-70) for timeline reloads
• Budget-Exempt — Reloads that don't count (user-initiated, app foregrounding, system-initiated)
• Widget Family — Size/shape (systemSmall, systemMedium, accessoryCircular, etc.)
• App Groups — Entitlement for shared data container between app and extensions
• ActivityAttributes — Static data (set once) + dynamic ContentState (updated during lifecycle)
• ContentState — Changing part of ActivityAttributes; must be under 4KB total
• Dynamic Island — iPhone 14 Pro+ Live Activity display; compact, minimal, and expanded sizes
• ControlWidget — iOS 18+ widgets for Control Center, Lock Screen, and Action Button
• Supplemental Activity Families — Enables Live Activities on Apple Watch or CarPlay

---

Part 1: Standard Widgets (iOS 14+)

Widget Configuration Types

StaticConfiguration

For widgets that don't require user configuration.

@main
struct MyWidget: Widget {
    let kind: String = "MyWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            MyWidgetEntryView(entry: entry)
        }
        .configurationDisplayName("My Widget")
        .description("This widget displays...")
        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
    }
}

AppIntentConfiguration (iOS 17+)

For widgets with user configuration using App Intents.

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

    var body: some WidgetConfiguration {
        AppIntentConfiguration(
            kind: kind,
            intent: SelectProjectIntent.self,
            provider: Provider()
        ) { entry in
            MyWidgetEntryView(entry: entry)
        }
        .configurationDisplayName("Project Status")
        .description("Shows your selected project")
    }
}

Migration from IntentConfiguration: iOS 16 and earlier used IntentConfiguration with SiriKit intents. Migrate to AppIntentConfiguration for iOS 17+.

ActivityConfiguration

For Live Activities (covered in Live Activities section).

Choosing the Right Configuration

No user configuration needed? Use StaticConfiguration. Simple static options? Use AppIntentConfiguration with WidgetConfigurationIntent. Dynamic options from app data? Use AppIntentConfiguration + EntityQuery.

Quick Reference:

• StaticConfiguration — No customization (weather, battery status)
• AppIntentConfiguration (simple) — Fixed options (timer presets, theme selection)
• AppIntentConfiguration (EntityQuery) — Dynamic list from app data (project/contact/playlist picker)
• ActivityConfiguration — Live ongoing events (delivery tracking, workout progress, sports scores)

Widget Families

System Families (Home Screen)

• systemSmall (~170×170, iOS 14+) — Single piece of info, icon
• systemMedium (~360×170, iOS 14+) — Multiple data points, chart
• systemLarge (~360×380, iOS 14+) — Detailed view, list
• systemExtraLarge (~720×380, iOS 15+ iPad only) — Rich layouts, multiple views

Accessory Families (Lock Screen, iOS 16+)

• accessoryCircular (~48×48pt) — Circular complication, icon or gauge
• accessoryRectangular (~160×72pt) — Above clock, text + icon
• accessoryInline (single line) — Above date, text only

Example: Supporting Multiple Families

struct MyWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "MyWidget", provider: Provider()) { entry in
            if #available(iOSApplicationExtension 16.0, *) {
                switch entry.family {
                case .systemSmall:
                    SmallWidgetView(entry: entry)
                case .systemMedium:
                    MediumWidgetView(entry: entry)
                case .accessoryCircular:
                    CircularWidgetView(entry: entry)
                case .accessoryRectangular:
                    RectangularWidgetView(entry: entry)
                default:
                    Text("Unsupported")
                }
            } else {
                LegacyWidgetView(entry: entry)
            }
        }
        .supportedFamilies([
            .systemSmall,
            .systemMedium,
            .accessoryCircular,
            .accessoryRectangular
        ])
    }
}

Timeline System

TimelineProvider Protocol

Provides entries that define when the system should render your widget.

struct Provider: TimelineProvider {
    // Placeholder while loading
    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: Date(), emoji: "😀")
    }

    // Shown in widget gallery
    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> ()) {
        let entry = SimpleEntry(date: Date(), emoji: "📷")
        completion(entry)
    }

    // Actual timeline
    func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> ()) {
        var entries: [SimpleEntry] = []
        let currentDate = Date()

        // Create entry every hour for 5 hours
        for hourOffset in 0 ..< 5 {
            let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset, to: currentDate)!
            let entry = SimpleEntry(date: entryDate, emoji: "⏰")
            entries.append(entry)
        }

        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    }
}

TimelineReloadPolicy

Controls when the system requests a new timeline:

• .atEnd — Reload after last entry
• .after(date) — Reload at specific date
• .never — No automatic reload (manual only)

Manual Reload

import WidgetKit

// Reload all widgets of this kind
WidgetCenter.shared.reloadAllTimelines()

// Reload specific kind
WidgetCenter.shared.reloadTimelines(ofKind: "MyWidget")

Performance & Budget Quick Reference

Timeline Refresh Budget

• Daily budget: 40-70 reloads/day (varies by system load and engagement)
• Budget-exempt: User-initiated reload, app foregrounding, widget added, system reboot
• Strategic (4x/hour) — ~48 reloads/day, low battery impact
• Aggressive (12x/hour) — Budget exhausted by 6 PM, high impact
• On-demand only — 5-10 reloads/day, minimal impact
• Reload on significant data changes and time-based events. Avoid speculative or cosmetic reloads.

// ✅ GOOD: Strategic intervals (15-60 min)
let entries = (0..<8).map { offset in
    let date = Calendar.current.date(byAdding: .minute, value: offset * 15, to: now)!
    return SimpleEntry(date: date, data: data)
}

Memory Limits

• ~30MB for standard widgets, ~50MB for Live Activities — system terminates if exceeded
• Load only what you need (e.g., loadRecentItems(limit: 10), not entire database)

Network Requests

Never make network requests in widget views — they won't complete before rendering. Fetch data in getTimeline() instead.

Timeline Generation

Complete getTimeline() in under 5 seconds. Cache expensive computations in the main app, read pre-computed data from shared container, limit to 10-20 entries.

View Rendering

Precompute everything in TimelineEntry, keep views simple. No expensive operations in body.

Images

• Use asset catalog images or SF Symbols (fast)
• Small images from shared container are acceptable
• AsyncImage does NOT work in widgets
• Large images cause memory termination

---

Part 2: Interactive Widgets (iOS 17+)

Button and Toggle

Interactive widgets use SwiftUI Button and Toggle with App Intents.

Button with App Intent

Button(intent: I

---

*Content truncated.*