How does a WidgetKit widget work: providers, timeline entries, reload policies, families and the refresh budget?

A widget is a SwiftUI view rendered from a timeline, hosted in a widget extension. You define a Widget with a StaticConfiguration (or an AppIntentConfiguration for user-configurable widgets), a provider (TimelineProvider, or AppIntentTimelineProvider) and an entry type conforming to TimelineEntry (it must have a date: when this snapshot becomes current). The provider answers three calls: placeholder(in:) (a redacted sample shown while loading and in the gallery, which must return instantly), getSnapshot(in:completion:) (a representative entry for the widget gallery, fast, with sample data if real data is slow) and getTimeline(in:completion:), which returns a Timeline(entries:policy:): several entries with future dates (so the widget can change over the next hours without being woken up, such as a calendar showing the next event, or a forecast by hour) and a reload policy: .atEnd (ask again after the last entry), .after(date) (ask again at that time) or .never (until the app calls WidgetCenter.shared.reloadTimelines(ofKind:) or reloadAllTimelines()). The system renders each entry’s view at its date, in a family: .systemSmall, .systemMedium, .systemLarge, .systemExtraLarge (iPad), and the accessory families for the Lock Screen and StandBy and the watch (.accessoryCircular, .accessoryRectangular, .accessoryInline), declared with supportedFamilies and read with @Environment(\.widgetFamily) so the view adapts.

The rules that matter. The system, not you, decides when to run the provider: each widget has a daily refresh budget (roughly 40 to 70 timeline reloads per day, higher for widgets the user looks at often, and not guaranteed), so put as many future entries as you can into one timeline instead of reloading often, and do not poll. Widgets cannot run code while visible: no timers, no animations beyond a few SwiftUI transitions, no network from the view; data must be fetched in getTimeline (a short async network call is allowed within the extension’s time limit) or prepared by the app into the shared container, and the view renders from the entry. For countdowns and clocks use the system text styles (Text(date, style: .timer), .relative) that the system updates itself. Memory is tiny (tens of MB), so downsample images and keep entries small. Reload from the app when data changes meaningfully (after a sync or user action) with WidgetCenter.shared.reloadTimelines(ofKind:), which counts against the budget but is the right trigger, and tell the system a widget is relevant for the Smart Stack with TimelineEntryRelevance and relevance intents. Deep link with widgetURL(_:) or Link in medium and large families (small has one tap target), and mark private content with .privacySensitive() and redacted placeholders so the Lock Screen can hide it. Debug with the widget schemes in Xcode (timeline preview and the debug-reload of Timeline Debug), and expect behaviour on a device to differ: budgets and low-power mode throttle you. If a widget “does not update”, check the policy, the budget, whether the app reloads it, whether the provider returns quickly, and whether the extension is being killed for memory.