WWDC 2026 - WidgetKit Foundations: A Practical Guide for Developers

What makes a widget worth building

Apple frames good widgets around three qualities, and they're worth keeping in your head as design constraints, not just slogans:

• Glanceable — someone should understand it in a fraction of a second. Think Weather showing you just enough of today's forecast.
• Relevant — content should match the moment, the place, and the person's patterns. Calendar surfacing your next event is the canonical example.
• Personalizable — it should be configurable with the content that matters to that specific user.

These three map directly onto the technical decisions you'll make: glanceable drives your view design, relevant drives your timeline strategy, and personalizable drives whether you reach for a configurable (App Intent) widget.

The mental model: how a widget actually runs

This is the part most newcomers get wrong, so it's worth being precise.

Your widgets are delivered to the system from a widget extension, which is a separate process from your app. That separation has a real consequence: your app can't just hand data to the extension in memory. You share data through an app group container — a shared database, or UserDefaults backed by the group. Wire this up early; it's the thing people forget.

Whether your app is UIKit or SwiftUI, the widgets themselves are always built in SwiftUI.

The data flow is:

1. WidgetKit asks your extension for content.
2. That content is a timeline — a series of timeline entries.
3. Each entry carries the data needed to render your view at a specific point in time.
4. The rendered views are archived, and the system displays each one at its relevant time.

The key insight hiding in step 4: your code is not running while the widget is on screen. The system renders archived views. This explains a lot of WidgetKit's API design, including why interactive elements use App Intents rather than closures.

Building your first widget

When you add a widget extension target, Xcode scaffolds most of what you need. The body returns a WidgetConfiguration, and you pick one of two types:

• StaticConfiguration — the widget configures itself. Simplest option.
• AppIntentConfiguration — the user configures it (more on this below).

For a widget that always shows "the book I'm currently reading," static configuration is the right call. It needs three things: a kind (a unique string identifier), a timeline provider, and a closure that turns an entry into a view.

struct DailyReadingGoalWidget: Widget {
    let kind = "DailyReadingGoalWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: kind,
            provider: DailyReadingGoalProvider()
        ) { entry in
            DailyReadingGoalView(book: entry.book,
                                 message: entry.message,
                                 timeOfDay: entry.timeOfDay)
            .environment(\.colorScheme, .dark)
            .containerBackground(for: .widget) {
                Background()
            }
        }
    }
}

Two things to call out here:

• You reuse your app's existing SwiftUI views. If your app is already SwiftUI, the view you pass to the closure is often a view you already have.
• containerBackground(for: .widget) is not optional polish. It tells the system which view is your background. When someone applies a colored or clear tint to their Home Screen, the system swaps that background for an adaptive glass material. Skip it and your widget will look broken in tinted environments.

The timeline provider: three states you must handle

Your provider supplies three distinct things, and conflating them is a common bug source:

Snapshot — a realistic preview shown in the widget gallery. This is your first impression, and crucially, your app may have zero user data at this point. Don't show an empty shell. Feature representative sample content (the session uses a popular book with a default message) so people can imagine the widget at its best before adding it.

Placeholder — the stand-in the system shows while your real timeline loads for the first time. It must appear instantly, so fetching a placeholder is synchronous — no disk reads, no network. The clean trick here is SwiftUI's .redacted(reason:) modifier to render a skeleton version of your real view.

Timeline entry — what your widget shows at a specific moment, now or in the future. Your provider returns a collection of these, and the system renders each at its time. Each entry should carry everything the view needs (message, progress, title, cover, etc.).

Reload policies: keeping content fresh without burning battery

Timelines eventually run out of entries and need refreshing — that's a reload. You declare reload behavior with one of three policies, and choosing correctly is most of the skill here.

.atEnd — reload once all entries are exhausted. Use it when there's no single known "refresh at" time but the timeline will run dry. A widget cycling motivational messages at varied times throughout the day fits this: reload when the last entry has been shown.

.afterDate — reload at a specific date you name. Use it when you know the moment things change. A daily schedule that recalculates at end of day is the textbook case: hand the system "today" and "tomorrow," set the reload for end of day, and provide a fresh schedule when you're asked again.

.never — the widget won't reload on its own. Use it when automatic reloads make no sense and updates are driven entirely by interaction. You then trigger refreshes explicitly via WidgetCenter's reload APIs or a push notification. A log that only changes when the user logs something fits here.

A few battery-and-budget realities worth internalizing:

• Provide multiple entries whenever possible so the system always has something to show.
• WidgetKit gives each widget an update budget, heavily influenced by how often the user actually looks at the widget. Frequent reloads while your app is in the foreground may be throttled.
• A good habit: if your data may have changed, fire one reload when your app enters the background.
• If your content is genuinely ephemeral — a defined start/end, frequent updates, alerting (think live sports) — that's not a widget, that's a Live Activity.

One widget, many sizes — and a new family

Once your extension and provider are wired up, supporting additional families is mostly view work. You list what you support with .supportedFamilies, reuse the same provider, and build a SwiftUI view that suits each shape.

struct DailyReadingGoalWidget: Widget {
    let kind = "DailyReadingGoalWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: kind,
            provider: DailyReadingGoalProvider()
        ) { entry in
            DailyReadingGoalView(book: entry.book,
                                 message: entry.message,
                                 timeOfDay: entry.timeOfDay)
            .environment(\.colorScheme, .dark)
            .containerBackground(for: .widget) {
                Background()
            }
        }
        .supportedFamilies([.systemMedium])
    }
}

Apple's guidance is to support as many sizes as make sense so people have placement choices — but starting with one or two families is perfectly fine. Notably, the system extra large portrait family (originally introduced on visionOS 26) is now coming to macOS, iOS, and iPadOS, giving large content a lot more room to breathe.

Also worth knowing: an iOS widget isn't confined to iOS. It can show up on CarPlay and as a remote widget on macOS without extra work — which is exactly why testing across environments matters later.

Integrating the widget with your app

A widget is an extension of your app, and there are three levers to tie them together.

Deep links

By default, tapping a widget opens your app. If the widget shows specific content, send people straight to it with .widgetURL. Encode whatever you need (here, a book ID) so the app launches directly to the right screen.

struct DailyReadingGoalWidget: Widget {
    let kind = "DailyReadingGoalWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: kind,
            provider: DailyReadingGoalProvider()
        ) { entry in
            DailyReadingGoalView(book: entry.book,
                                 message: entry.message,
                                 timeOfDay: entry.timeOfDay)
            .environment(\.colorScheme, .dark)
            .containerBackground(for: .widget) {
                Background()
            }
            .widgetURL(URL(string: "bookclub://reading/\(book.bookID)"))
        }
        .supportedFamilies([.systemMedium])
    }
}

Configurable widgets

This is where AppIntentConfiguration earns its place. Let people pick the content the widget tracks — a location for weather, a specific book to log, and so on. Configurable widgets also let users add several copies with different settings (three widgets, three books).

Apple's practical rules for configuration are good ones:

• Ask whether content should differ per user before adding configuration at all.
• Keep it fast — one or two parameters is usually enough.
• Don't require configuration up front. Provide a sensible default (the most recently read book, for instance) so the widget is useful immediately and tweakable later.

If you're going down this road, the relevant deep dive is Explore enhancements to App Intents (WWDC23).

Interactive elements

Buttons and toggles let people act directly from the widget — checking off a task, completing a chapter. Remember the archived-view reality: your code isn't running on screen, so buttons and toggles take an App Intent the system executes on your behalf. Pick the single most important action in your app and surface that one. For the full treatment, see Bring widgets to life (WWDC23).

Adapting to tinted and clear environments (don't skip this)

On iOS the Home Screen can be tinted with a color or set to a clear style. In those modes the system renders your widget through a glass material — tinting your content and replacing your background with adaptive glass. SwiftUI handles most of it (this is also why containerBackground matters), but you still have to verify.

The session walks through a real bug: in clear mode, a book cover image rendered as a plain white rectangle because the system couldn't accent it correctly. The fix is to tell the system how that image should render:

struct BookCoverImage: View {
    let imageName: String

    var body: some View {
        Image(imageName: bundle: .main)
            .widgetAccentedRenderingMode(.fullColor)
    }
}

Using .fullColor keeps the cover art in its original colors even in accented rendering mode. The broader lesson: imagery especially needs an explicit rendering decision, because the system's default accenting can mangle photographic or full-color assets.

A testing checklist before you ship

Pulling the session's testing advice into a list you can actually run through:

• Test on real devices in full color, tinted, and clear modes.
• Remember iOS widgets appear as remote widgets on macOS — verify interactions still feel right from a Mac.
• Lean on SwiftUI previews: the Xcode canvas lets you flip through families, color schemes, and rendering modes without leaving the editor.
• Turn on WidgetKit developer mode during testing to lift constraints like reload budgets so you can iterate quickly.

The takeaways

If you remember nothing else:

• A widget extension is a separate process; share data through an app group.
• Content is a timeline of entries; handle snapshot, placeholder, and timeline distinctly, and keep placeholders synchronous.
• Pick a reload policy that matches reality — .atEnd, .afterDate, or .never — and respect the update budget.
• Use containerBackground and widgetAccentedRenderingMode so the widget survives tinted and clear Home Screens.
• Tie it to your app with deep links, configuration, and interactive App Intents — and test everywhere the widget can appear, including macOS.

Widgets remain one of the highest-leverage surfaces you can add to an app: small to build, and a genuine extension of your app's reach across the system. This session is a clean foundation to build on.