iOS Widget Development with WidgetKit: Timeline Providers, Entries, and Display

WidgetKit lets you ship widgets that live on the iOS Home Screen, Lock Screen, StandBy mode, and iPadOS Today View - plus Apple Watch complications via the same framework. They're built in SwiftUI, refresh on a budget set by iOS, and follow a strict declarative model: you give iOS a timeline of future entries, and iOS displays them when the time comes. This guide covers the production-ready WidgetKit patterns for 2026.

TimelineProvider and Entry: the core protocol

A widget is fundamentally a TimelineProvider that returns Entries. Each Entry has a date and the data needed to render the widget at that date. The system asks for a timeline, picks entries based on time, and renders them.

The protocol has three methods: placeholder (returns a generic entry for the widget gallery before data loads), getSnapshot (returns one entry quickly for previews), and getTimeline (returns a full sequence of entries for the next refresh window).

For an electricity price widget, getTimeline would fetch the next 24 hours of hourly prices, build one Entry per hour, and return them all in a single Timeline. The timeline policy controls when iOS asks again. .atEnd means iOS will request a new timeline after the last entry expires. .never means don't ask again (static content). .after(date) means ask after a specific time, useful for irregular updates.

The widget view receives an entry and renders it via standard SwiftUI. The entry has a date field plus whatever payload your widget needs - prices, weather, tasks, calendar events. Keep the rendering fast: widgets are rendered into rasterised images by iOS, so dynamic SwiftUI animations and lazy loading don't apply.

Widget families, refresh budget, and complications

Widget families. A single widget can support multiple sizes - small, medium, large on iPhone; extraLarge on iPad; accessoryCircular, accessoryRectangular, accessoryInline on Lock Screen and Watch. Declare supported families in the widget configuration via .supportedFamilies([.systemSmall, .systemMedium, .accessoryCircular, ...]).

The widget view should switch on the family to render appropriately for each size. Use @Environment(\.widgetFamily) inside the view body to access it. Small widgets typically show one number prominently; medium widgets add a chart or secondary detail; large widgets can show full lists or 24-hour timelines.

Refresh budget. iOS strictly limits how often a widget can be reloaded with fresh data. There's no published exact number, but for most apps: expect 40-70 reloads per day per widget. Apps where the user actively engages with widgets get more budget; apps where the widget is ignored get less.

Practical implication: don't try to refresh every 5 minutes. Instead, fetch enough data in one call to populate the next 24 hours of entries, return a timeline with all 24 entries, and let iOS display them at the right times without needing further reloads.

Apple Watch complications. WidgetKit replaced ClockKit complications starting watchOS 9. The same Provider + Entry + View architecture works for complications. The complication families are .accessoryCircular, .accessoryRectangular, .accessoryInline, .accessoryCorner - same as iOS Lock Screen widgets.

Watch faces have their own complication slot conventions (corner, top-leading, top-trailing, etc.) but at the widget code level they're all the accessory families. iOS picks which slot to show based on the user's watch face configuration.

Quick comparison

Common pitfalls and how to avoid them

Across every domain this article touches, the same shape of mistake recurs. Practitioners new to the field overweight the most visible piece of the system — the screenshot, the paywall, the exam question, the headline price — and underweight the underlying constraint that actually determines outcomes.

The five most common failure modes:

1. Optimising for the demo, not the durability. A working demo in a controlled environment proves nothing about reliability under real conditions. In iOS development, an in-app purchase flow that works in the Xcode Simulator says nothing about how it behaves in App Store sandbox with network latency and Ask to Buy approvals. In an exam, a 100% score on an untimed quiz tells you nothing about whether you can do 49/50 in 45 minutes with no second guesses. Build for the hardest realistic case from the start.
2. Skipping the first-principles documentation. Every system has a canonical specification. App Review Guidelines for iOS, the official EU regulations for tax deductibility, the CITB question bank for CSCS, the OMIE market rules for Spanish electricity. Reading them takes a few hours but saves weeks of wrong-direction work. Secondary sources (blogs, tutorials, this article included) are useful as orientation but never authoritative.
3. Ignoring the rate limit. Every external system has rate limits — explicit (APNs silent push throttling, RevenueCat API quotas, exam retake fees) or implicit (App Review patience, customer attention spans, your own working memory). Plan around them. A workflow that requires more rate-limited operations than the system allows will fail in production, not on day one but during the first stress event.
4. Underweighting localisation and regional variation. What is true for Germany is not always true for Italy. What is true for English-speaking users is not always true for Japanese ones. What is true for the UK CSCS test is not always true for the Irish equivalent. Always check the local rule before applying a general one.
5. Treating the documentation as static. Apple updates App Review Guidelines. The Bundeslaender change Schonzeiten. OMIE adjusts market clearing algorithms. Set up a periodic review (quarterly is enough for most things) and re-read the canonical sources. Workflows that worked perfectly a year ago can be silently broken today.

None of these are dramatic. The dramatic mistakes (catastrophic bugs, audit findings, exam failures) are the visible tip of a longer-running iceberg of small misses. Catching the small misses is what separates routine outcomes from problematic ones.

Key takeaways

• TimelineProvider — Generates timeline. Multiple entries per call.
• Entry struct — Snapshot of data. Pass to View.
• Family — Widget size. @Environment.
• Refresh — iOS budget. Batch via timeline.

The pattern that runs through every section above: start with the constraint, not the wishlist. In an exam, the constraint is the question bank and the pass mark. In an electricity market, it is the auction clearing rule. In a tax workflow, it is the receipt-retention requirement. In a code architecture, it is the platform's design decision (StoreKit's transaction lifecycle, App Review's guideline, APNs's authentication model). Get the constraint right and the rest follows.

The opposite failure mode — designing for an aesthetic ideal, then trying to retro-fit the constraint — is the most common cause of wasted work in every domain covered here. A beautiful paywall that hangs in sandbox is rejected at App Review. A polished freelancer expense report that lacks receipts is disallowed by the tax office. A study plan that ignores the actual question distribution leaves the candidate stuck below the pass mark.

The practical recommendation: read the official rules of whatever system you are operating in, extract the binding constraints, and treat them as inputs to the design — not afterthoughts. Every section of this article is the application of that principle to a specific domain.

FAQ

How often does iOS refresh widgets?
It's not a fixed number. Expect 40-70 reloads per day for actively-used widgets, fewer for ignored ones. Batch your data into multi-hour timelines instead of relying on frequent reloads.

Can widgets make network requests?
Yes, via URLSession in the TimelineProvider. Keep them fast (under 5 seconds) and small (under 1 MB). Use App Group shared UserDefaults to cache between widget reload and host app launch.

Do I need a separate target for widgets?
Yes. Widgets run as a separate extension target with their own Info.plist and entitlements. Share code via a Swift Package or by adding source files to both targets.

Can I show interactive UI in a widget?
From iOS 17 onwards, widgets support limited interactivity via Button and Toggle that call AppIntents. Use sparingly - widgets are still primarily display surfaces, not full apps.

Further reading and references

The references below cover the official sources for the rules cited in this article. Where applicable, they include the canonical documentation, regulatory text, or vendor-provided guides. For each one, prefer the official source over secondary commentary — secondary sources go stale fast and frequently misquote the binding rule.

• Official documentation of the system in question (linked from each app or service's own help centre).
• Apple Developer Documentation for any iOS/macOS reference — the WWDC session videos and the corresponding Human Interface Guidelines pages are the authoritative source.
• For EU regulatory questions (taxation, data protection, energy market structure), consult the relevant national authority — most publish their guidance in English.
• For Spain and Italy energy market data, OMIE and GME both publish full historical price series in CSV format from their public websites — no API key required.
• For UK CSCS prep, the CITB publishes the official question bank book each year — buy a current copy if you want the authoritative source.

If you find a contradiction between this article and an official source, the official source wins. Article rules of thumb are summaries — they have edge cases, exceptions, and regional variations that the source documents specify exactly.