Widgetkit

WidgetKit Documentation

Search these docs to answer questions about widget development.

Return Format

Always include: 1. Summary - Answer the question concisely 2. File paths - List relevant files for full details, e.g.:

• widgetkit-overview.md for widget basics
• widgetkit-timelineprovider.md for timeline providers

Files

• widgetkit-overview.md - Framework overview and widget families
• widgetkit-timelineentry.md - Timeline entry protocol
• widgetkit-timelineprovider.md - Providing widget timeline data

Navigation: WidgetKit

Essentials

• Developing a WidgetKit strategy
• WidgetKit updates
• Creating a widget extension
• Emoji Rangers: Supporting Live Activities, interactivity, and animations
• WidgetBundle

System experiences

• Widgets and watch complications

Widget creation

• Creating a widget extension
• Developing a WidgetKit strategy
• Emoji Rangers: Supporting Live Activities, interactivity, and animations
• Preparing widgets for additional platforms, contexts, and appearances
• Widget
• WidgetFamily

Accessing system families

• case systemSmall
• case systemMedium
• case systemLarge
• case systemExtraLarge
• case systemExtraLargePortrait

Accessing accessory families

• case accessoryCircular
• case accessoryCorner
• case accessoryRectangular
• case accessoryInline

• StaticConfiguration

Creating a widget configuration

• init<Provider>(kind: String, provider: Provider, content: (Provider.Entry) -> Content))
• var body: Self.Body

Setting the display name

• [func configurationDisplayName<S>(S) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-2c3zv)

• [func configurationDisplayName(Text) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-3sbn4)

• [func configurationDisplayName(LocalizedStringKey) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-4v9q)

Setting the description

• [func description(Text) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-1bvuj)

• [func description<S>(S) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-2bfr)

• [func description(LocalizedStringKey) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-4q9pa)

Setting the supported families

• [func supportedFamilies([WidgetFamily]) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/supportedfamilies(_:))

• [func supplementalActivityFamilies([ActivityFamily]) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/supplementalactivityfamilies(_:))

Handling background network requests

• [func backgroundTask<D, R>(BackgroundTask<D, R>, action: (D) async -> R) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/backgroundtask(_:action:))

• [func onBackgroundURLSessionEvents(matching: ((String) -> Bool)?, (String, () -> Void) -> Void) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/onbackgroundurlsessionevents(matching:_:)-2e152)

• [func onBackgroundURLSessionEvents(matching: String, (String, () -> Void) -> Void) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/onbackgroundurlsessionevents(matching:_:)-fw6x)

Configurable widgets

• Making a configurable widget
• Migrating widgets from SiriKit Intents to App Intents
• AppIntentConfiguration

Creating a widget configuration

• init<Provider>(kind: String, intent: Intent.Type, provider: Provider, content: (Provider.Entry) -> Content))
• var body: Self.Body

Setting the display name

• [func configurationDisplayName<S>(S) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-2c3zv)

• [func configurationDisplayName(Text) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-3sbn4)

• [func configurationDisplayName(LocalizedStringKey) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-4v9q)

Setting the description

• [func description(Text) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-1bvuj)

• [func description<S>(S) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-2bfr)

• [func description(LocalizedStringKey) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-4q9pa)

Setting the supported families

• [func supportedFamilies([WidgetFamily]) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/supportedfamilies(_:))

Handling background network requests

• [func backgroundTask<D, R>(BackgroundTask<D, R>, action: (D) async -> R) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/backgroundtask(_:action:))

• [func onBackgroundURLSessionEvents(matching: ((String) -> Bool)?, (String, () -> Void) -> Void) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/onbackgroundurlsessionevents(matching:_:)-2e152)

• [func onBackgroundURLSessionEvents(matching: String, (String, () -> Void) -> Void) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/onbackgroundurlsessionevents(matching:_:)-fw6x)

• WidgetInfo

Getting Configured Widget Information

• let kind: String
• let family: WidgetFamily
• let configuration: INIntent?

Identifying Widget Information

• var id: WidgetInfo

Instance Methods

• func widgetConfigurationIntent<Intent>(of: Intent.Type) -> Intent?)

Default Implementations

• Identifiable Implementations

Instance Properties

• var id: WidgetInfo

Layout and presentation

• Supporting additional widget sizes
• Displaying the right widget background
• Optimizing your widget for accented rendering mode and Liquid Glass
• Adding StandBy and CarPlay support to your widget
• WidgetRenderingMode

Rendering modes

• static let fullColor: WidgetRenderingMode
• static let accented: WidgetRenderingMode
• static let vibrant: WidgetRenderingMode

• WidgetAccentedRenderingMode

Type Properties

• static let accented: WidgetAccentedRenderingMode
• static let accentedDesaturated: WidgetAccentedRenderingMode
• static let desaturated: WidgetAccentedRenderingMode
• static let fullColor: WidgetAccentedRenderingMode

• AccessoryWidgetBackground

Creating accessory widget backgrounds

• init())

• WidgetLocation

Specifying a location style

• static let carPlay: WidgetLocation
• static let iPhoneWidgetsOnMac: WidgetLocation
• static let homeScreen: WidgetLocation
• static let lockScreen: WidgetLocation
• static let smartStack: WidgetLocation
• static let standBy: WidgetLocation
• static let watchFace: WidgetLocation

Timeline updates

• Keeping a widget up to date
• TimelineProvider

Generating Timelines

• func getSnapshot(in: Self.Context, completion: (Self.Entry) -> Void))
• func getTimeline(in: Self.Context, completion: (Timeline<Self.Entry>) -> Void))
• func placeholder(in: Self.Context) -> Self.Entry)
• Entry
• TimelineProvider.Context

Providing relevance clues

• func relevance() async -> WidgetRelevance<Void>)

TimelineProvider Implementations

• func relevance() async -> WidgetRelevance<Void>-7036j)

• AppIntentTimelineProvider

Generating timelines

• func placeholder(in: Self.Context) -> Self.Entry)
• [func recommendations() -> [AppIntentRecommendation<Self.Intent>]](/documentation/widgetkit/appintenttimelineprovider/recommendations())

AppIntentTimelineProvider Implementations

• [func recommendations() -> [AppIntentRecommendation<Self.Intent>]](/documentation/widgetkit/appintenttimelineprovider/recommendations()-5xfj5)

• func relevance() async -> WidgetRelevance<Self.Intent>)

AppIntentTimelineProvider Implementations

• func relevance() async -> WidgetRelevance<Self.Intent>-9vl5j)

• func snapshot(for: Self.Intent, in: Self.Context) async -> Self.Entry)
• func timeline(for: Self.Intent, in: Self.Context) async -> Timeline<Self.Entry>)
• AppIntentTimelineProvider.Context
• Entry
• Intent

• IntentTimelineProvider

Generating Timelines

• func getSnapshot(for: Self.Intent, in: Self.Context, completion: (Self.Entry) -> Void))
• func getTimeline(for: Self.Intent, in: Self.Context, completion: (Timeline<Self.Entry>) -> Void))
• func placeholder(in: Self.Context) -> Self.Entry)
• Entry
• Intent
• [func recommendations() -> [IntentRecommendation<Self.Intent>]](/documentation/widgetkit/intenttimelineprovider/recommendations())

IntentTimelineProvider Implementations

• [func recommendations() -> [IntentRecommendation<Self.Intent>]](/documentation/widgetkit/intenttimelineprovider/recommendations()-5qmcg)

• IntentTimelineProvider.Context

Instance Methods

• func relevance() async -> WidgetRelevance<Self.Intent>)

IntentTimelineProvider Implementations

• func relevance() async -> WidgetRelevance<Self.Intent>-4bbqo)

• TimelineProviderContext

Preparing Preview Content

• let isPreview: Bool

Accessing Size Attributes

• let family: WidgetFamily
• let displaySize: CGSize

Accessing Environment Variations

• let environmentVariants: TimelineProviderContext.EnvironmentVariants
• TimelineProviderContext.EnvironmentVariants

Subscripts

• [subscript<T>(WritableKeyPath<EnvironmentValues, T>) -> [T]?](/documentation/widgetkit/timelineprovidercontext/environmentvariants-swift.struct/subscript(_:))
• [subscript<T>(dynamicMember _: WritableKeyPath<EnvironmentValues, T>) -> [T]?](/documentation/widgetkit/timelineprovidercontext/environmentvariants-swift.struct/subscript(dynamicmember:))

• TimelineEntry

Configuring Timeline Entry Properties

• var date: Date
• var relevance: TimelineEntryRelevance?

TimelineEntry Implementations

• var relevance: TimelineEntryRelevance?

• Timeline

Creating a Timeline

• [init(entries: [EntryType], policy: TimelineReloadPolicy)](/documentation/widgetkit/timeline/init(entries:policy:))

Getting Timeline Properties

• [let entries: [EntryType]](/documentation/widgetkit/timeline/entries)
• let policy: TimelineReloadPolicy
• TimelineReloadPolicy

Reload Policies

• static let atEnd: TimelineReloadPolicy
• static func after(Date) -> TimelineReloadPolicy)
• static let never: TimelineReloadPolicy

• WidgetCenter

Getting Widget Information

• static let shared: WidgetCenter
• [func getCurrentConfigurations((Result<[WidgetInfo], any Error>) -> Void)](/documentation/widgetkit/widgetcenter/getcurrentconfigurations(_:))
• WidgetCenter.UserInfoKey

Describing a widget

• static let family: String
• static let kind: String

Describing a Live Activity

• static let activityID: String

Reloading Widget Timelines

• func reloadTimelines(ofKind: String))
• func reloadAllTimelines())

Reloading Recommended Preconfigured Widgets

• func invalidateConfigurationRecommendations())

Instance Properties

• var currentPushInfo: WidgetPushInfo?

Instance Methods

• [func currentConfigurations() async throws -> [WidgetInfo]](/documentation/widgetkit/widgetcenter/currentconfigurations())
• func invalidateRelevance(ofKind: String))

Push notification updates

• Updating widgets with WidgetKit push notifications
• WidgetPushHandler

Initializers

• init())

Instance Methods

• [func pushTokenDidChange(WidgetPushInfo, widgets: [WidgetInfo])](/documentation/widgetkit/widgetpushhandler/pushtokendidchange(_:widgets:))

• WidgetPushInfo

Instance Properties

• let token: Data

Capabilities

• Accessing location information in widgets
• Making network requests in a widget extension

Debugging

• Previewing widgets and Live Activities in Xcode
• Preview macros

Generating a widget preview

• macro Preview<Widget, Provider>(String?, as: WidgetFamily, widget: () -> Widget, timelineProvider: () -> Provider))
• macro Preview<Widget, Provider>(String?, as: WidgetFamily, using: Provider.Intent, widget: () -> Widget, timelineProvider: () -> Provider)-4ljg1)
• macro Preview<Widget, Provider>(String?, as: WidgetFamily, using: Provider.Intent, widget: () -> Widget, timelineProvider: () -> Provider)-3df1l)
• [macro Preview<Widget>(String?, as: WidgetFamily, widget: () -> Widget, timeline: () async -> [any TimelineEntry])](/documentation/widgetkit/preview(_:as:widget:timeline:))
• [macro Preview<Widget, Entry>(String?, widget: () -> Widget, relevanceEntries: () async -> [Entry])](/documentation/widgetkit/preview(_:widget:relevanceentries:))
• macro Preview<Widget, Provider>(String?, widget: () -> Widget, relevanceProvider: () -> Provider))
• macro Preview<Widget, Provider>(String?, widget: () -> Widget, relevanceProvider: () -> Provider, relevance: () async -> WidgetRelevance<Provider.Configuration>))

Generating a Live Activity preview

• [macro Preview<Widget, Attributes>(String?, as: ActivityPreviewViewKind, using: Attributes, widget: () -> Widget, contentStates: () async -> [Attributes.ContentState])](/documentation/widgetkit/preview(_:as:using:widget:contentstates:))

Generated structures

• PreviewActivityBuilder

Previewing Live Activities

• [static func buildArray([[A.ContentState]]) -> [A.ContentState]](/documentation/widgetkit/previewactivitybuilder/buildarray(_:))
• [static func buildExpression(A.ContentState) -> [A.ContentState]](/documentation/widgetkit/previewactivitybuilder/buildexpression(_:))
• [static func buildPartialBlock(accumulated: [A.ContentState], next: [A.ContentState]) -> [A.ContentState]](/documentation/widgetkit/previewactivitybuilder/buildpartialblock(accumulated:next:))
• [static func buildPartialBlock(first: [A.ContentState]) -> [A.ContentState]](/documentation/widgetkit/previewactivitybuilder/buildpartialblock(first:))

• PreviewRelevanceEntryBuilder

Previewing relevance widgets

• [static func buildArray([[Entry]]) -> [Entry]](/documentation/widgetkit/previewrelevanceentrybuilder/buildarray(_:))
• [static func buildExpression(Entry) -> [Entry]](/documentation/widgetkit/previewrelevanceentrybuilder/buildexpression(_:))
• [static func buildPartialBlock(first: [Entry]) -> [Entry]](/documentation/widgetkit/previewrelevanceentrybuilder/buildpartialblock(first:))
• [static func buildPartialBlock(accumulated: [Entry], next: [Entry]) -> [Entry]](/documentation/widgetkit/previewrelevanceentrybuilder/buildpartialblock(accumulated:next:))

• PreviewTimelineBuilder

Previewing timelines

• [static func buildArray([[any TimelineEntry]]) -> [any TimelineEntry]](/documentation/widgetkit/previewtimelinebuilder/buildarray(_:))
• [static func buildExpression(some TimelineEntry) -> [any TimelineEntry]](/documentation/widgetkit/previewtimelinebuilder/buildexpression(_:))
• [static func buildPartialBlock(accumulated: [any TimelineEntry], next: [any TimelineEntry]) -> [any TimelineEntry]](/documentation/widgetkit/previewtimelinebuilder/buildpartialblock(accumulated:next:))
• [static func buildPartialBlock(first: [any TimelineEntry]) -> [any TimelineEntry]](/documentation/widgetkit/previewtimelinebuilder/buildpartialblock(first:))

• WidgetPreviewContext

Creating a Preview Context

• init(family: WidgetFamily))

• Debugging widgets

visionOS widgets

• Updating your widgets for visionOS
• [func widgetTexture(WidgetTexture) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/widgettexture(_:))

• WidgetTexture

Textures

• static let glass: WidgetTexture
• static let paper: WidgetTexture

• [func supportedMountingStyles([WidgetMountingStyle]) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/supportedmountingstyles(_:))

• WidgetMountingStyle

Type Properties

• static let elevated: WidgetMountingStyle
• static let recessed: WidgetMountingStyle

• LevelOfDetail

Type Properties

• static let `default`: LevelOfDetail
• static let simplified: LevelOfDetail

Accessory and watchOS widgets

• Creating accessory widgets and watch complications
• AccessoryWidgetGroup

Initializers

• init(some StringProtocol, content: () -> Content)-3ij0e)
• init(LocalizedStringResource, content: () -> Content)-75rkg)
• init(LocalizedStringKey, content: () -> Content)-nb0)
• init(LocalizedStringResource, image: ImageResource, content: () -> Content)-385rt)
• init(LocalizedStringKey, image: ImageResource, content: () -> Content)-50iyk)
• init(some StringProtocol, image: ImageResource, content: () -> Content)-66iys)
• init(LocalizedStringResource, systemImage: String, content: () -> Content)-3mynu)
• init(LocalizedStringKey, systemImage: String, content: () -> Content)-54h9w)
• init(some StringProtocol, systemImage: String, content: () -> Content)-7rnqc)
• init(label: () -> Label, content: () -> Content))

• AccessoryWidgetGroupStyle

Type Properties

• static let automatic: AccessoryWidgetGroupStyle
• static let circular: AccessoryWidgetGroupStyle
• static let roundedSquare: AccessoryWidgetGroupStyle

• Migrating ClockKit complications to WidgetKit

Smart Stacks

• Increasing the visibility of widgets in Smart Stacks
• TimelineEntryRelevance

Creating a Relevance Object

• init(score: Float, duration: TimeInterval))

Configuring Relevance Properties

• var duration: TimeInterval
• var score: Float

• RelevanceConfiguration

Creating a relevance configuration

• init<Provider>(kind: String, provider: Provider, content: (Provider.Entry) -> Content))

• RelevanceEntriesProvider

Generating relevance entries

• func entry(configuration: Self.Configuration, context: Self.Context) async throws -> Self.Entry)
• func relevance() async -> WidgetRelevance<Self.Configuration>)
• func placeholder(context: Self.Context) -> Self.Entry)
• RelevanceEntriesProviderContext

Instance Properties

• let displaySize: CGSize
• let isPreview: Bool

Associated Types

• Configuration
• Entry

Type Aliases

• RelevanceEntriesProvider.Context

• RelevanceEntry
• WidgetRelevance

Initializers

• [init([WidgetRelevanceAttribute<Configuration>])](/documentation/widgetkit/widgetrelevance/init(_:))

• WidgetRelevanceAttribute

Initializers

• init(configuration: Configuration, context: RelevantContext)-8325r)
• init(configuration: Configuration, context: RelevantContext)-8jxhs)
• init(configuration: Configuration, group: WidgetRelevanceGroup)-5yh17)
• init(configuration: Configuration, group: WidgetRelevanceGroup)-93jm5)
• init(context: RelevantContext))
• init(group: WidgetRelevanceGroup))

• WidgetRelevanceGroup

Type Properties

• static let automatic: WidgetRelevanceGroup
• static let ungrouped: WidgetRelevanceGroup

Type Methods

• static func named(String) -> WidgetRelevanceGroup)

• AppIntentRecommendation

Creating a recommended widget configuration

• init(intent: Intent, description: LocalizedStringKey)-2p4dh)
• init(intent: Intent, description: Text)-65igj)
• init(intent: Intent, description: some StringProtocol)-7zn32)

Initializers

• init(intent: Intent, description: LocalizedStringResource)-3j1cv)

• IntentConfiguration

Creating a widget configuration

• init<Provider>(kind: String, intent: Intent.Type, provider: Provider, content: (Provider.Entry) -> Content))
• var body: Self.Body

Setting the display name

• [func configurationDisplayName<S>(S) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-2c3zv)

• [func configurationDisplayName(Text) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-3sbn4)

• [func configurationDisplayName(LocalizedStringKey) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/configurationdisplayname(_:)-4v9q)

Setting the description

• [func description(Text) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-1bvuj)

• [func description<S>(S) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-2bfr)

• [func description(LocalizedStringKey) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/description(_:)-4q9pa)

Setting the supported families

• [func supportedFamilies([WidgetFamily]) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/supportedfamilies(_:))

Handling background network requests

• [func backgroundTask<D, R>(BackgroundTask<D, R>, action: (D) async -> R) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/backgroundtask(_:action:))

• [func onBackgroundURLSessionEvents(matching: ((String) -> Bool)?, (String, () -> Void) -> Void) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/onbackgroundurlsessionevents(matching:_:)-2e152)

• [func onBackgroundURLSessionEvents(matching: String, (String, () -> Void) -> Void) -> some WidgetConfiguration

](/documentation/swiftui/widgetconfiguration/onbackgroundurlsessionevents(matching:_:)-fw6x)

• IntentRecommendation

Creating a Recommended Widget Configuration

• init(intent: T, description: LocalizedStringKey)-1zh33)
• init(intent: T, description: Text)-4epo2)
• init<S>(intent: T, description: S)-6v7dj)

Initializers

• init(intent: T, description: LocalizedStringResource)-6o8yy)

• Live Activities

Essentials

• Developing a WidgetKit strategy
• Creating a widget extension

Live Activity setup

• Displaying live data with Live Activities
• ActivityKit
• Creating a widget extension
• Emoji Rangers: Supporting Live Activities, interactivity, and animations
• ActivityConfiguration

Creating a Live Activity configuration

• ActivityViewContext

Describing a Live Activity

• let attributes: Attributes
• let state: Attributes.ContentState
• let isStale: Bool
• let activityID: String

• init<Content>(for: Attributes.Type, content: (ActivityViewContext<Attributes>) -> Content, dynamicIsland: (ActivityViewContext<Attributes>) -> DynamicIsland))

• DynamicIsland

Creating the view for the Dynamic Island

• init<Expanded, CompactLeading, CompactTrailing, Minimal>(expanded: () -> DynamicIslandExpandedContent<Expanded>, compactLeading: () -> CompactLeading, compactTrailing: () -> CompactTrailing, minimal: () -> Minimal))
• DynamicIslandExpandedRegion

Creating the expanded presentation

• init(DynamicIslandExpandedRegionPosition, priority: Double, content: () -> Content))
• DynamicIslandExpandedRegionPosition

View positions

• static let bottom: DynamicIslandExpandedRegionPosition
• static let center: DynamicIslandExpandedRegionPosition
• static let leading: DynamicIslandExpandedRegionPosition
• static let trailing: DynamicIslandExpandedRegionPosition

• [func dynamicIsland(verticalPlacement: DynamicIslandExpandedRegionVerticalPlacement) -> some View

](/documentation/swiftui/view/dynamicisland(verticalplacement:))

• DynamicIslandExpandedRegionVerticalPlacement

Configuring vertical content placement

• static let `default`: DynamicIslandExpandedRegionVerticalPlacement
• static let belowIfTooWide: DynamicIslandExpandedRegionVerticalPlacement

• DynamicIslandExpandedContent
• DynamicIslandExpandedContentBuilder

Type Methods

• [static func buildPartialBlock<C0, C1>(accumulated: DynamicIslandExpandedContent<C0>, next: DynamicIslandExpandedContent<C1>) -> DynamicIslandExpandedContent<some View>

](/documentation/widgetkit/dynamicislandexpandedcontentbuilder/buildpartialblock(accumulated:next:)-39sr0)

• [static func buildPartialBlock<C0, C1>(accumulated: DynamicIslandExpandedContent<C0>, next: DynamicIslandExpandedRegion<C1>) -> DynamicIslandExpandedContent<some View>

](/documentation/widgetkit/dynamicislandexpandedcontentbuilder/buildpartialblock(accumulated:next:)-3jswv)

• [static func buildPartialBlock<C>(first: DynamicIslandExpandedRegion<C>) -> DynamicIslandExpandedContent<some View>

](/documentation/widgetkit/dynamicislandexpandedcontentbuilder/buildpartialblock(first:)-5j108)

• [static func buildPartialBlock<C>(first: DynamicIslandExpandedContent<C>) -> DynamicIslandExpandedContent<some View>

](/documentation/widgetkit/dynamicislandexpandedcontentbuilder/buildpartialblock(first:)-74hpw)

Specifying custom content margins

• func contentMargins(Edge.Set, Double) -> DynamicIslandExpandedRegion<Content>)

Deep linking

• func widgetURL(URL?) -> DynamicIsland)

Setting a tint color

• func keylineTint(Color?) -> DynamicIsland)

Specifying content margins

• func contentMargins(Edge.Set, Double, for: DynamicIslandMode) -> DynamicIsland)
• DynamicIslandMode

Dynamic Island presentations

• static let compactLeading: DynamicIslandMode
• static let compactTrailing: DynamicIslandMode
• static let expanded: DynamicIslandMode
• static let minimal: DynamicIslandMode

• let NSUserActivityTypeLiveActivity: String
• ActivityPreviewViewKind

Live Activity preview types

• case content
• case dynamicIsland(ActivityPreviewViewKind.DynamicIslandPreviewViewState))
• ActivityPreviewViewKind.DynamicIslandPreviewViewState

Dynamic Island presentations

• case compact
• case minimal
• case expanded

• ActivityFamily

Accessing system families

• case small
• case medium

Environment keys

• SupportedActivityFamiliesEnvironmentKey

• Controls

Essentials

• Developing a WidgetKit strategy
• Creating a widget extension
• Emoji Rangers: Supporting Live Activities, interactivity, and animations

Setup and configuration

• Creating controls to perform actions across the system
• Adding refinements and configuration to controls
• StaticControlConfiguration

Initializers

• init(kind: String, content: () -> Content))
• init<Provider>(kind: String, provider: Provider, content: (Provider.Value) -> Content))

• AppIntentControlConfiguration

Initializers

• init(kind: String, intent: Configuration.Type, content: (Configuration) -> Content))
• init<Provider>(kind: String, provider: Provider, content: (Provider.Value) -> Content))

• ControlCenter

Instance Methods

• [func currentControls() async throws -> [ControlInfo]](/documentation/widgetkit/controlcenter/currentcontrols())
• func reloadAllControls())
• func reloadControls(ofKind: String))

Type Properties

• static let shared: ControlCenter

• ControlInfo

Instance Properties

• let kind: String
• var pushInfo: ControlPushInfo?

Instance Methods

• func configurationIntent<Intent>(of: Intent.Type) -> Intent?)

Default Implementations

• Identifiable Implementations

Instance Properties

• var id: String

• ControlWidgetButton

Initializers

• init(action: Action, label: () -> Label)-77p8j)
• init(action: Action, label: () -> Label)-8oxxp)
• init(action: Action, label: () -> Label, actionLabel: (Bool) -> ActionLabel))
• init(action: Action, label: () -> Label, actionLabel: (Bool) -> ActionLabel))
• init(some StringProtocol, action: Action, actionLabel: (Bool) -> ActionLabel)-4sgji)
• init(LocalizedStringKey, action: Action, actionLabel: (Bool) -> ActionLabel)-67uvw)
• init(LocalizedStringResource, action: Action, actionLabel: (Bool) -> ActionLabel)-1kxch)

Default action label

• ControlWidgetButtonDefaultActionLabel

• ControlWidgetToggle

Initializers

• init(isOn: Bool, action: Action, label: () -> Label))
• init(isOn: Bool, action: Action, label: () -> Label, valueLabel: (Bool) -> ValueLabel))
• init(some StringProtocol, isOn: Bool, action: Action, valueLabel: (Bool) -> ValueLabel)-33wfq)
• init(LocalizedStringKey, isOn: Bool, action: Action, valueLabel: (Bool) -> ValueLabel)-5o6bn)
• init(LocalizedStringResource, isOn: Bool, action: Action, valueLabel: (Bool) -> ValueLabel)-4lk32)

Default action label

• ControlWidgetToggleDefaultLabel

Updates

• Updating controls locally and remotely
• ControlPushHandler

Initializers

• init())

Instance Methods

• [func pushTokensDidChange(controls: [ControlInfo])](/documentation/widgetkit/controlpushhandler/pushtokensdidchange(controls:))

• ControlPushInfo

Instance Properties

• let token: Data

Previews

• ControlValueProvider

Associated Types

• Value

Instance Properties

• var previewValue: Self.Value

Instance Methods

• func currentValue() async throws -> Self.Value)

• AppIntentControlValueProvider

Associated Types

• Configuration
• Value

Instance Methods

• func currentValue(configuration: Self.Configuration) async throws -> Self.Value)
• func previewValue(configuration: Self.Configuration) -> Self.Value)

Presentation

• Creating views for widgets, Live Activities, and watch complications
• SwiftUI views for widgets

Displaying text

• Displaying dynamic dates in widgets
• Text

Showing images

• Image

Adding interaction

• Adding interactivity to widgets and Live Activities
• Button
• Toggle

Adding labels and links

• Label
• Link

Stacking views

• HStack
• VStack
• ZStack
• LazyHStack
• LazyVStack

Arranging views in grids

• LazyHGrid
• LazyVGrid
• GridItem

Enumerating lists

• ForEach

Grouping views

• Group
• GroupBox
• Section

Representing hierarchies

• OutlineGroup

Adding spacers and dividers

• Spacer
• Divider

Handling conditional views

• EmptyView
• EquatableView

Displaying shapes

• Rectangle
• RoundedRectangle
• Circle
• Ellipse
• Capsule
• Path

Transforming views

• ScaledShape
• RotatedShape
• OffsetShape
• TransformedShape
• ContainerRelativeShape

Styling views

• Color
• ImagePaint
• Gradient
• LinearGradient
• AngularGradient
• RadialGradient
• ForegroundStyle
• FillStyle
• BackgroundStyle
• SelectionShapeStyle
• SeparatorShapeStyle
• StrokeStyle

Creating 2D graphics

• Canvas

Managing view geometry

• GeometryProxy
• GeometryReader
• ProjectionTransform

Substituting views

• AnyView
• TupleView

Interactivity

• Adding interactivity to widgets and Live Activities
• Animating data updates in widgets and Live Activities
• Linking to specific app scenes from your widget or Live Activity

Accessibility

• Adding accessible descriptions to widgets and Live Activities

Previews and debugging

• Previewing widgets and Live Activities in Xcode
• WidgetPreviewContext

Creating a Preview Context

• init(family: WidgetFamily))

• Preview macros

Generating a widget preview

• macro Preview<Widget, Provider>(String?, as: WidgetFamily, widget: () -> Widget, timelineProvider: () -> Provider))
• macro Preview<Widget, Provider>(String?, as: WidgetFamily, using: Provider.Intent, widget: () -> Widget, timelineProvider: () -> Provider)-4ljg1)
• macro Preview<Widget, Provider>(String?, as: WidgetFamily, using: Provider.Intent, widget: () -> Widget, timelineProvider: () -> Provider)-3df1l)
• [macro Preview<Widget>(String?, as: WidgetFamily, widget: () -> Widget, timeline: () async -> [any TimelineEntry])](/documentation/widgetkit/preview(_:as:widget:timeline:))
• [macro Preview<Widget, Entry>(String?, widget: () -> Widget, relevanceEntries: () async -> [Entry])](/documentation/widgetkit/preview(_:widget:relevanceentries:))
• macro Preview<Widget, Provider>(String?, widget: () -> Widget, relevanceProvider: () -> Provider))
• macro Preview<Widget, Provider>(String?, widget: () -> Widget, relevanceProvider: () -> Provider, relevance: () async -> WidgetRelevance<Provider.Configuration>))

Generating a Live Activity preview

• [macro Preview<Widget, Attributes>(String?, as: ActivityPreviewViewKind, using: Attributes, widget: () -> Widget, contentStates: () async -> [Attributes.ContentState])](/documentation/widgetkit/preview(_:as:using:widget:contentstates:))

Generated structures

• PreviewActivityBuilder

Previewing Live Activities

• [static func buildArray([[A.ContentState]]) -> [A.ContentState]](/documentation/widgetkit/previewactivitybuilder/buildarray(_:))
• [static func buildExpression(A.ContentState) -> [A.ContentState]](/documentation/widgetkit/previewactivitybuilder/buildexpression(_:))
• [static func buildPartialBlock(accumulated: [A.ContentState], next: [A.ContentState]) -> [A.ContentState]](/documentation/widgetkit/previewactivitybuilder/buildpartialblock(accumulated:next:))
• [static func buildPartialBlock(first: [A.ContentState]) -> [A.ContentState]](/documentation/widgetkit/previewactivitybuilder/buildpartialblock(first:))

• PreviewRelevanceEntryBuilder

Previewing relevance widgets

• [static func buildArray([[Entry]]) -> [Entry]](/documentation/widgetkit/previewrelevanceentrybuilder/buildarray(_:))
• [static func buildExpression(Entry) -> [Entry]](/documentation/widgetkit/previewrelevanceentrybuilder/buildexpression(_:))
• [static func buildPartialBlock(first: [Entry]) -> [Entry]](/documentation/widgetkit/previewrelevanceentrybuilder/buildpartialblock(first:))
• [static func buildPartialBlock(accumulated: [Entry], next: [Entry]) -> [Entry]](/documentation/widgetkit/previewrelevanceentrybuilder/buildpartialblock(accumulated:next:))

• PreviewTimelineBuilder

Previewing timelines

• [static func buildArray([[any TimelineEntry]]) -> [any TimelineEntry]](/documentation/widgetkit/previewtimelinebuilder/buildarray(_:))
• [static func buildExpression(some TimelineEntry) -> [any TimelineEntry]](/documentation/widgetkit/previewtimelinebuilder/buildexpression(_:))
• [static func buildPartialBlock(accumulated: [any TimelineEntry], next: [any TimelineEntry]) -> [any TimelineEntry]](/documentation/widgetkit/previewtimelinebuilder/buildpartialblock(accumulated:next:))
• [static func buildPartialBlock(first: [any TimelineEntry]) -> [any TimelineEntry]](/documentation/widgetkit/previewtimelinebuilder/buildpartialblock(first:))

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: WidgetKit

Protocol

TimelineEntry

Available on: iOS 14.0+, iPadOS 14.0+, Mac Catalyst, macOS 11.0+, visionOS 26.0+, watchOS 9.0+

A type that specifies the date to display a widget, and, optionally, indicates the current relevance of the widget’s content.

protocol TimelineEntry

Overview

A TimelineProvider creates one or more timeline entries with dates that tell WidgetKit when to display a widget. To render a widget, WidgetKit executes the content block of the widget’s configuration, passing the corresponding timeline entry.

When you declare a structure conforming to TimelineEntry, include any additional information that the configuration’s content block requires to render the widget. The following code shows a timeline entry structure for a widget that displays a game character’s health level.

struct CharacterDetailEntry: TimelineEntry {
    var date: Date
    var healthLevel: Double
}

The content block of the widget’s configuration receives the entry as a parameter and then passes the relevant information to the view that renders your widget.

struct CharacterDetailWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "com.mygame.character-detail",
            provider: CharacterDetailProvider()) { entry in
            CharacterDetailView(entry: entry)
        }
        .configurationDisplayName("Character Details")
        .description("Displays a character's health and other details")
        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
    }
}

Configuring Timeline Entry Properties

• date The date for WidgetKit to render a widget.
• relevance The relevance of a widget’s content to the user.

Timeline updates

• Keeping a widget up to date Plan your widget’s timeline to show timely, relevant information using dynamic views, and update the timeline when things change.
• TimelineProvider A type that advises WidgetKit when to update a widget’s display.
• AppIntentTimelineProvider A type that advises WidgetKit when to update a user-configurable widget’s display.
• IntentTimelineProvider A type that advises WidgetKit when to update a user-configurable widget’s display.
• TimelineProviderContext An object that contains details about how a widget is rendered, including its size and whether it appears in the widget gallery.
• Timeline An object that specifies a date for WidgetKit to update a widget’s view.
• WidgetCenter An object that contains a list of user-configured widgets and is used for reloading widget timelines.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: WidgetKit

Protocol

TimelineProvider

Available on: iOS 14.0+, iPadOS 14.0+, Mac Catalyst, macOS 11.0+, visionOS 26.0+, watchOS 9.0+

A type that advises WidgetKit when to update a widget’s display.

protocol TimelineProvider

Overview

At various times, WidgetKit requests a timeline from the provider. A timeline is an array of objects conforming to TimelineEntry. Each timeline entry has a date, and you can specify additional properties for displaying the widget.

For example, consider a widget that displays the health level of a game character. In the game, when the character’s health level is below 100 percent, it recovers at a rate of 25 percent per hour. If the character’s health level is 25 percent, the provider creates a timeline consisting of the following entries:

The following code shows the structure encapsulating this information.

struct CharacterDetailEntry: TimelineEntry {
    var date: Date
    var healthLevel: Double
}

WidgetKit asks for timeline entries in one of two ways:

• A single immediate snapshot, representing the widget’s current state.
• An array of entries, including the current moment and, if known, any future dates when the widget’s state will change.

WidgetKit makes the snapshot request when displaying the widget in transient situations, such as when the user is adding a widget. WidgetKit provides a context parameter that includes details about how to use the entry, including whether it’s a preview for the widget gallery, and the family, or size, of the widget to display. If context.isPreview is true, the widget appears in the widget gallery and requires a quick response from your provider. If the information you need to generate the snapshot is not readily available, or requires additional time to load, use sample data instead. For example, if determining the character’s health level requires fetching data from a server, the widget could show the health level at 75 percent. The following code shows how the game widget might implement its snapshot method.

struct CharacterDetailProvider: TimelineProvider {
    func getSnapshot(in context: Context, completion: @escaping (Entry) -> Void) {
        let date = Date()
        let entry: CharacterDetailEntry

        if context.isPreview && !hasHealthLevel {
            entry = CharacterDetailEntry(date: date, healthLevel: 0.75)
        } else {
            entry = CharacterDetailEntry(date: date, healthLevel: currentHealthLevel)
        }
        completion(entry)
    }
}

WidgetKit makes the timeline request after the user adds your widget from the widget gallery. Because your widget extension is not always running, WidgetKit needs to know when to activate it to update the widget. The timeline your provider generates informs WidgetKit when you would like to update the widget. The following example shows how the Emoji Rangers: Supporting Live Activities, interactivity, and animations sample code project creates a timeline for its leaderboard widget.

func getTimeline(in context: Context, completion: @escaping (Timeline<LeaderboardEntry>) -> Void) {
    EmojiRanger.loadLeaderboardData { (heros, error) in
        guard let heros else {
            let timeline = Timeline(entries: [LeaderboardEntry(date: Date(), heros: EmojiRanger.availableHeros)], policy: .atEnd)

            completion(timeline)

            return
        }
        let timeline = Timeline(entries: [LeaderboardEntry(date: Date(), heros: heros)], policy: .atEnd)
        completion(timeline)
    }
}

If your provider needs to do asynchronous work to generate the timeline, such as fetching data from a server, store a reference to the completion handler and call it when you are done with your asynchronous work.

Determine a refresh policy

When creating the timeline, the provider specifies a refresh policy that controls when WidgetKit requests a new timeline. The default behavior is to use atEnd to request a new timeline after the last date specified by the entries in a timeline. However, if there is a different date when WidgetKit should request a new timeline, you can specify a refresh policy of after(_:)). For example, a dragon will appear in 2.5 hours and might engage in battle with the game character. Because the outcome of this battle may change the character’s health level, the provider can tell WidgetKit to request a new timeline after the battle.

// Request a timeline refresh after 2.5 hours.
let date = Calendar.current.date(byAdding: .minute, value: 150, to: Date())!
let timeline = Timeline(entries: entries, policy: .after(date))
completion(timeline)

Other examples of when it makes sense to use a different date include:

• In a widget displaying stock market details, you might specify the next market opening or closing date because information typically doesn’t change overnight or during weekends.
• A flight tracking widget might continue showing a “flight landed” indication after the flight lands. In this case, you could specify a date later than when the flight lands so that its status remains visible for a while before being cleared.

Alternatively, if future events are unpredictable, you can tell WidgetKit to not request a new timeline at all by specifying never for the policy. In that case, your app calls the WidgetCenter function reloadTimelines(ofKind:)) when a new timeline is available. Some examples of when using never makes sense include:

• When the user has a widget configured to display the health of a character, but that character is no longer actively engaging in battle and its health level won’t change.
• When a widget’s content is dependent on the user being logged into an account and they aren’t currently logged in.

In both examples, when your app determines that the status has changed, it calls the WidgetCenter function reloadTimelines(ofKind:)) and WidgetKit requests a new timeline.

Refresh widgets efficiently

Each configured widget receives a limited number of refreshes every day. Several factors affect how many refreshes a widget receives, such as whether the containing app is running in the foreground or background, how frequently the widget is shown onscreen, and what types of activities the containing app engages in.

Note: WidgetKit does not impose this limit when debugging your widget in Xcode. To verify that your widget behaves correctly, test your app and widget’s behavior outside of Xcode’s debugger.

Use the following approaches to optimize your widget refreshes:

• Have the containing app prepare data for the widget in advance of when the widget needs it. Use a shared group container to store the data.
• Use background processing time in your app to keep shared data up to date. For more information, see Using background tasks to update your app.
• Choose the most appropriate refresh policy for the information being shown, as described in the preceding section.
• Call reloadTimelines(ofKind:)) only when information the widget is currently displaying changes.

When your app is in the foreground, has an active media session, or is using the standard location service, refreshes don’t count against the widget’s daily limit. For more information about media sessions and location services, see AVAudioSession and Configuring your app to use location services.

Generating Timelines

• getSnapshot(in:completion:)) Provides a timeline entry that represents the current time and state of a widget.
• getTimeline(in:completion:)) Provides an array of timeline entries for the current time and, optionally, any future times to update a widget.
• placeholder(in:)) Provides a timeline entry representing a placeholder version of the widget.
• Entry A type that specifies the date to display a widget, and, optionally, indicates the current relevance of the widget’s content.
• TimelineProvider.Context An object that contains details about how a widget is rendered, including its size and whether it appears in the widget gallery.

Providing relevance clues

• relevance()) Provides an object containing attributes that describe when a specific widget is relevant.

Timeline updates

• Keeping a widget up to date Plan your widget’s timeline to show timely, relevant information using dynamic views, and update the timeline when things change.
• AppIntentTimelineProvider A type that advises WidgetKit when to update a user-configurable widget’s display.
• IntentTimelineProvider A type that advises WidgetKit when to update a user-configurable widget’s display.
• TimelineProviderContext An object that contains details about how a widget is rendered, including its size and whether it appears in the widget gallery.
• TimelineEntry A type that specifies the date to display a widget, and, optionally, indicates the current relevance of the widget’s content.
• Timeline An object that specifies a date for WidgetKit to update a widget’s view.
• WidgetCenter An object that contains a list of user-configured widgets and is used for reloading widget timelines.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.