App Services · IOS API REFERENCE

WidgetKit

Extend the reach of your app by creating widgets, watch complications, Live Activities, and controls.

76 types

120 callable entries

119 skipped

50% entry coverage

Generated from iOS SDK 27.1. Availability is shown on each declaration; permissions and entitlements still apply.

Types

AccessoryWidgetBackground

struct · iOS 16.0+

AccessoryWidgetBackground.Body

typealias · iOS 16.0+

ActivityConfiguration

struct · iOS 16.1+

ActivityConfiguration.Body

typealias · iOS 16.1+

ActivityFamily

enum · iOS 18.0+

ActivityFamily.RawValue

typealias · iOS 18.0+

ActivityPreviewViewKind

enum · iOS 16.2+

ActivityPreviewViewKind.DynamicIslandPreviewViewState

enum · iOS 16.2+

ActivityViewContext

struct · iOS 16.1+

AppIntentConfiguration

struct · iOS 17.0+

AppIntentConfiguration.Body

typealias · iOS 17.0+

AppIntentControlConfiguration

struct · iOS 18.0+

AppIntentControlConfiguration.Body

typealias · iOS 18.0+

AppIntentControlValueProvider

protocol · iOS 18.0+

AppIntentRecommendation

struct · iOS 17.0+

AppIntentTimelineProvider

protocol · iOS 17.0+

AppIntentTimelineProvider.Context

typealias · iOS 17.0+

ControlCenter

class · iOS 18.0+

ControlInfo

struct · iOS 18.0+

ControlInfo.ID

typealias · iOS 18.0+

ControlPushHandler

protocol · iOS 18.0+

ControlPushInfo

struct · iOS 18.0+

ControlValueProvider

protocol · iOS 18.0+

ControlWidgetButton

struct · iOS 18.0+

ControlWidgetButton.Body

typealias · iOS 18.0+

ControlWidgetButtonDefaultActionLabel

struct · iOS 18.0+

ControlWidgetButtonDefaultActionLabel.Body

typealias · iOS 18.0+

ControlWidgetToggle

struct · iOS 18.0+

ControlWidgetToggle.Body

typealias · iOS 18.0+

ControlWidgetToggleDefaultLabel

struct · iOS 18.0+

ControlWidgetToggleDefaultLabel.Body

typealias · iOS 18.0+

DynamicIsland

struct · iOS 16.1+

DynamicIslandExpandedContent

struct · iOS 16.1+

DynamicIslandExpandedContentBuilder

struct · iOS 16.1+

DynamicIslandExpandedRegion

struct · iOS 16.1+

DynamicIslandExpandedRegionPosition

struct · iOS 16.1+

DynamicIslandExpandedRegionVerticalPlacement

struct · iOS 16.1+

DynamicIslandMode

struct · iOS 16.1+

IntentConfiguration

struct · iOS 14.0+

IntentConfiguration.Body

typealias · iOS 14.0+

IntentRecommendation

struct · iOS 16.0+

IntentTimelineProvider

protocol · iOS 14.0+

IntentTimelineProvider.Context

typealias · iOS 14.0+

LevelOfDetail

struct · iOS 26.0+

PreviewActivityBuilder

struct · iOS 17.0+

PreviewTimelineBuilder

struct · iOS 17.0+

StaticConfiguration

struct · iOS 14.0+

StaticConfiguration.Body

typealias · iOS 14.0+

StaticControlConfiguration

struct · iOS 18.0+

StaticControlConfiguration.Body

typealias · iOS 18.0+

SupportedActivityFamiliesEnvironmentKey

struct · iOS 18.0+

SupportedActivityFamiliesEnvironmentKey.Value

typealias · iOS 18.0+

Timeline

struct · iOS 14.0+

TimelineEntry

protocol · iOS 14.0+

TimelineEntryRelevance

struct · iOS 14.0+

TimelineProvider

protocol · iOS 14.0+

TimelineProvider.Context

typealias · iOS 14.0+

TimelineProviderContext

struct · iOS 14.0+

TimelineProviderContext.EnvironmentVariants

struct · iOS 14.0+

TimelineReloadPolicy

struct · iOS 14.0+

WidgetAccentedRenderingMode

struct · iOS 18.0+

WidgetCenter

class · iOS 14.0+

WidgetCenter.UserInfoKey

struct · iOS 14.0+

WidgetFamily

enum · iOS 14.0+

WidgetFamily.RawValue

typealias · iOS 14.0+

WidgetInfo

struct · iOS 14.0+

WidgetInfo.ID

typealias · iOS 14.0+

WidgetLocation

struct · iOS 17.0+

WidgetMountingStyle

struct · iOS 26.0+

WidgetPreviewContext

struct · iOS 14.0+

WidgetPushHandler

protocol · iOS 26.0+

WidgetPushInfo

struct · iOS 26.0+

WidgetRelevance

struct · iOS 18.0+

WidgetRelevanceAttribute

struct · iOS 18.0+

WidgetRelevanceGroup

struct · iOS 18.0+

WidgetRenderingMode

struct · iOS 16.0+

Functions and constants

get

NSUserActivityTypeLiveActivity

TypeScript

const NSUserActivityTypeLiveActivity: string

Swift declaration

let NSUserActivityTypeLiveActivity: String

get · iOS 15.0+

showsWidgetContainerBackground

TypeScript

get showsWidgetContainerBackground(): boolean

Swift declaration

var showsWidgetContainerBackground: Bool { get }

An environment variable that indicates whether the background of a widget appears. In iOS 16 and earlier, this environment variable is always `true` for system widgets and `false` for accessory widgets. In macOS 13 and earlier, and in watchOS 9 and earlier, it always evaluates to `true`. If you pass `false` to <doc://com.apple.documentation/documentation/swiftui/widgetconfiguration/containerbackgroundremovable(_:)> to always show the widget background, the system shows the widget background even if `showsWidgetContainerBackground` evaluates to `true`. - Returns: `true` if, by default, the background appears in this context; `false` otherwise.

get · iOS 16.0+

showsWidgetLabel

TypeScript

get showsWidgetLabel(): boolean

Swift declaration

var showsWidgetLabel: Bool { get set }

A Boolean value that indicates whether an accessory family widget can display an accessory label. Use this value to determine if you can provide additional content, or possibly move some of the widget's content out of the main view and into the widget label. ```swift @Environment(\.widgetFamily) var widgetFamily @Environment(\.showsWidgetLabel) var showsWidgetLabel var body: some View { switch widgetFamily { case .accessoryCircular: if showsWidgetLabel { Image("cat_full") .widgetLabel(label: Text("Cats")) } else { VStack { Image("cat_small") Text("Cats") } } } } ``` This environment value is most useful when defining the appearance for the <doc://com.apple.documentation/documentation/widgetkit/widgetfamily/accessoryCircular> widget family, because it's value can change depending on where the widget appears. For example, if the widget is the top circular complication on the Infograph watch face, the value is `true`. Otherwise it is `false`. The environment variable is always `false` in iOS. Other families always have the same value, regardless of where the widget appears. For the <doc://com.apple.documentation/documentation/widgetkit/widgetfamily/accessoryCorner> widget family, the value is always `true`. For other families, it is `false`.

set · iOS 16.0+

showsWidgetLabel

TypeScript

set showsWidgetLabel(value: boolean)

Swift declaration

var showsWidgetLabel: Bool { get set }

get · iOS 14.0+

widgetFamily

TypeScript

get widgetFamily(): WidgetFamily

Swift declaration

var widgetFamily: WidgetFamily { get }

The template of the widget --- small, medium, or large. Use this value to retrieve the widget size that the user chose for a widget.

get · iOS 26.0+

levelOfDetail

TypeScript

get levelOfDetail(): LevelOfDetail

Swift declaration

var levelOfDetail: LevelOfDetail { get set }

The level of detail the view is recommended to have. Read from the environment with @Environment(\.levelOfDetail) var levelOfDetail To customize your view based on recommended level of detail, read the environment value using the `.levelOfDetail` key and apply that to change your view. ``` swift var body: some View { switch levelOfDetail { case .default: VStack { NewsTitleView() NewsBodyView() } case .simplified: NewsImageOverview() } } ``` > Note: The levelOfDetail can be determined by different factors depending on the platforms.

set · iOS 26.0+

levelOfDetail

TypeScript

set levelOfDetail(value: LevelOfDetail)

Swift declaration

var levelOfDetail: LevelOfDetail { get set }

get · iOS 18.0+

activityFamily

TypeScript

get activityFamily(): ActivityFamily

Swift declaration

var activityFamily: ActivityFamily { get set }

The size family of the current Live Activity. A Live Activity you initiate on one device can also appear on a remote device that renders the Live Activity in a different family size. As a result, it renders for a specific family, depending on both the device and the location in which it appears. For example, when rendering on the iOS or iPadOS Lock Screen, the current family is <doc://com.apple.comdumentation/documentation/WidgetKit/ActivityFamily/medium>. Use <doc://com.apple.documentation/documentation/swiftui/widgetconfiguration/supplementalactivityfamilies(_:)> to opt in and allow your Live Activity to render with additional families.

set · iOS 18.0+

activityFamily

TypeScript

set activityFamily(value: ActivityFamily)

Swift declaration

var activityFamily: ActivityFamily { get set }

get · iOS 16.0+

widgetRenderingMode

TypeScript

get widgetRenderingMode(): WidgetRenderingMode

Swift declaration

var widgetRenderingMode: WidgetRenderingMode { get set }

The widget's rendering mode, based on where the system is displaying it. You can read the rendering mode from the environment values using this key. ``` swift @Environment(\.widgetRenderingMode) var widgetRenderingMode ``` Then modify the widget's appearance based on the mode. ``` swift var body: some View { ZStack { switch renderingMode { case .fullColor: Text("Full color") case .accented: ZStack { Circle(...) VStack { Text("Accented") .widgetAccentable() Text("Normal") } } case .vibrant: Text("Full color") default: ... } } } ```

set · iOS 16.0+

widgetRenderingMode

TypeScript

set widgetRenderingMode(value: WidgetRenderingMode)

Swift declaration

var widgetRenderingMode: WidgetRenderingMode { get set }

get · iOS 16.1+

isActivityFullscreen

TypeScript

get isActivityFullscreen(): boolean

Swift declaration

@backDeployed(before: iOS 17.0)
var isActivityFullscreen: Bool { get }

A Boolean value that indicates whether the Live Activity appears in a full-screen presentation. When a Live Activity fills the entire screen, the system extends the background tint color you set with the <doc://com.apple.documentation/documentation/SwiftUI/View/activityBackgroundTint(_:)> modifier to fill the screen. Note that this environment variable is always `false` in iOS 16.

get · iOS 17.0+

widgetContentMargins

TypeScript

get widgetContentMargins(): _SwiftUICore_EdgeInsets

Swift declaration

var widgetContentMargins: EdgeInsets { get }

A property that identifies the content margins of a widget. The content margins of a widget depend on the context in which it appears. The system applies default content margins. However, if you disable automatic application of default content margins with <doc://com.apple.documentation/swiftui/WidgetConfiguration/contentMarginsDisabled()>, the system uses the `widgetContentMargins` property in combination with <doc://com.apple.documentation/documentation/swiftui/view/padding(_:)> to selectively apply default content margins. - Returns: Returns the content margins for the current widget presentation context.

get · iOS 18.0+

isActivityUpdateReduced

TypeScript

get isActivityUpdateReduced(): boolean

Swift declaration

var isActivityUpdateReduced: Bool { get set }

A Boolean value that indicates whether the Live Activity update synchronization rate is reduced. When rendering an activity on a remote device such as Apple Watch, content updates may sometimes be limited to only alerting updates, depending on system conditions. When a Live Activity is visible and the system synchronizes only alerting updates with a remote device, the value of `isActivityUpdateReduced` is `true`. For example, `isActivityUpdateReduced` may be `true` for Live Activities on an Apple Watch that's out of range of the paired iPhone.

set · iOS 18.0+

isActivityUpdateReduced

TypeScript

set isActivityUpdateReduced(value: boolean)

Swift declaration

var isActivityUpdateReduced: Bool { get set }

get · iOS 18.0+

supportedActivityFamilies

TypeScript

get supportedActivityFamilies(): Array<ActivityFamily>

Swift declaration

var supportedActivityFamilies: Set<ActivityFamily> { get set }

An environment value that that indicates potential rendered family for a Live Activity. To detect the currently rendered activity family size, use the <doc://com.apple.documentation/documentation/swiftui/environmentvalues/activityfamily> environment variable. The `supportedActivityFamilies` environment value might only be useful if your make you make your Live Activity views available in a Swift package.

set · iOS 18.0+

supportedActivityFamilies

TypeScript

set supportedActivityFamilies(value: Array<ActivityFamily>)

Swift declaration

var supportedActivityFamilies: Set<ActivityFamily> { get set }

get · iOS 27.0+

isDynamicIslandLimitedInWidth

TypeScript

get isDynamicIslandLimitedInWidth(): boolean

Swift declaration

var isDynamicIslandLimitedInWidth: Bool { get }

A Boolean value that indicates whether the Dynamic Island view displays with a limited width. This applies to `compactLeading`, `compactTrailing`, and `minimal` Live Activity DynamicIsland views.

get · iOS 17.0+

widget

TypeScript

static get widget(): _SwiftUI_ContainerBackgroundPlacement

Swift declaration

static let widget: ContainerBackgroundPlacement

The container background placement for a widget. Pass the container background placement to the <doc://com.apple.documentation/documentation/swiftui/view/containerbackground(_:for:)> function to configure the background of your widgets.

init · iOS 18.0+

init

TypeScript

static initConfigurationGroup(configuration: _Intents_INIntent, group: WidgetRelevanceGroup): WidgetRelevanceAttribute<_Intents_INIntent>

Swift declaration

init(configuration: Configuration, group: WidgetRelevanceGroup)

Associates the widget kind with a group. When multiple widgets are in the same group, the system will only suggest one member of the group simultaneously. Widgets in the same group are interpreted to contain redundant information, and therefore should not be presented together. Multiple groups can be associated with the same widget by providing multiple `WidgetRelevanceAttribute` instances with different groups. - Parameters: - configuration: The specific configuration - group: the group to associate the widget with

init · iOS 18.0+

init

TypeScript

static initConfigurationContext(configuration: _Intents_INIntent, context: _RelevanceKit_RelevantContext): WidgetRelevanceAttribute<_Intents_INIntent>

Swift declaration

init(configuration: Configuration, context: RelevantContext)

Creates a new widget relevance for a specific configuration that is relevant in a specific context. For example, a weather widget could specify that a configuration for a specific location is relevant for a the relevant context at that specific location. - Parameters: - configuration: The specific configuration - context: the relevant context where this widget is relevant.

init · iOS 18.0+

init

TypeScript

static initGroup(group: WidgetRelevanceGroup): WidgetRelevanceAttribute<void>

Swift declaration

init(group: WidgetRelevanceGroup)

Associates the widget kind with a group. When multiple widgets are in the same group, the system only suggests one member of the group simultaneously. Widgets in the same group are interpreted to contain redundant information, and therefore should not be presented together. Multiple groups can be associated with the same widget by providing multiple `WidgetRelevanceAttribute` instances with different groups. - Parameters: - group: the group to associate the widget with

init · iOS 18.0+

init

TypeScript

static initContext(context: _RelevanceKit_RelevantContext): WidgetRelevanceAttribute<void>

Swift declaration

init(context: RelevantContext)

Creates a new widget relevance that is relevant in a specific context. - Parameters: - context: the relevant context where this widget is relevant.

init · iOS 18.0+

init

TypeScript

static init(attributes: Array<WidgetRelevanceAttribute<unknown>>): WidgetRelevance<unknown>

Swift declaration

init(_ attributes: [WidgetRelevanceAttribute<Configuration>])

Creates a type collecting the relevances for a widget kind. - Parameters: - attributes: a collection of `WidgetRelevanceAttribute` describing when this type of widget could be relevant.

get · iOS 16.1+

activityID

TypeScript

get activityID(): string

Swift declaration

let activityID: String

A unique identifier for the Live Activity.

get · iOS 16.2+

isStale

TypeScript

get isStale(): boolean

Swift declaration

let isStale: Bool

A Boolean value that describes whether the Live Activity is out of date.

init · iOS 16.0+

init

TypeScript

static initIntentDescription(intent: _Intents_INIntent, description: _Foundation_LocalizedStringResource): IntentRecommendation<_Intents_INIntent>

Swift declaration

init(intent: T, description: LocalizedStringResource)

Creates a recommended configuration for a widget on platforms that don't offer a dedicated user interface to customize widgets with a localized description. > Note: On platforms that offer a dedicated user interface for configuring widgets — for example, iOS or macOS — `IntentRecommendation` is inactive. - Parameter intent: The intent that represents the recommended configuration. - Parameter description: A localized string in your bundle that helps the user understand the value of the preconfigured configuration option. For example, if the configuration represents a location in a weather app, the description may be the name of one of the user's favorite cities, such as `Cupertino`.

init · iOS 16.0+

init

TypeScript

static initIntentDescription61273(intent: _Intents_INIntent, description: _SwiftUICore_LocalizedStringKey): IntentRecommendation<_Intents_INIntent>

Swift declaration

init(intent: T, description: LocalizedStringKey)

Creates a recommended configuration for a widget on platforms that don't offer a dedicated user interface to customize widgets with a localized description. > Note: On platforms that offer a dedicated user interface for configuring widgets — for example, iOS or macOS — `IntentRecommendation` is inactive. - Parameter intent: The intent that represents the recommended configuration. - Parameter description: A key for a localized string in your bundle that helps the user understand the value of the preconfigured configuration option. For example, if the configuration represents a location in a weather app, the description may be the name of one of the user's favorite cities, such as `Cupertino`.

init · iOS 16.0+

init

TypeScript

static initIntentDescription4176(intent: _Intents_INIntent, description: _SwiftUICore_Text): IntentRecommendation<_Intents_INIntent>

Swift declaration

init(intent: T, description: Text)

Creates a recommended configuration for a widget on platforms that don't offer a dedicated user interface to customize widgets. > Note: On platforms that offer a dedicated user interface for configuring widgets — for example, iOS or macOS — `IntentRecommendation` is inactive. - Parameter intent: The intent that represents the recommended configuration. - Parameter description: A description that helps the user understand the value of the preconfigured configuration option. For example, if the configuration represents a location in a weather app, the description may be the name of one of the user's favorite cities, such as `Cupertino`.

init · iOS 16.0+

init

TypeScript

static initIntentDescription44801(intent: _Intents_INIntent, description: string): IntentRecommendation<_Intents_INIntent>

Swift declaration

init<S>(intent: T, description: S) where S : StringProtocol

method · iOS 16.1+

contentMargins

TypeScript

contentMargins(edges: _SwiftUICore_Edge_Set, length: number): DynamicIslandExpandedRegion<SDKHandle>

Swift declaration

func contentMargins(_ edges: Edge.Set = .all, _ length: Double) -> DynamicIslandExpandedRegion<Content>

Overrides default content margins for the provided edges in the Dynamic Island. If you repeatedly use the `contentMargins(_:_:)` modifier, the system uses the innermost specified values. The following example results in a margin of 8 points for the trailing, top, and bottom edges, and uses the default margin for the leading edge: ```swift DynamicIslandContentRegion(.trailing) { ContainerRelativeShape() .aspectRatio(1, contentMode:.fit) }.contentMargins([.trailing, .top, .bottom], 8) ``` Note that the system applies the provided custom content margins to content that’s adjacent to the modified content margin edges. - Parameters: - edges: The edges that use the custom content margins. - length: The length of the custom margin for the given `edges`. - Returns: The view for the Dynamic Island expanded region with the updated content margins.

get · iOS 14.0+

policy

TypeScript

get policy(): TimelineReloadPolicy

Swift declaration

let policy: TimelineReloadPolicy

The policy that determines the earliest date and time WidgetKit requests a new timeline from a timeline provider.

Skipped declarations

119 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.

AppIntentConfiguration.body

This protocol needs associated types that cannot yet cross the bridge.

AppIntentRecommendation.init(intent:description:)

This declaration needs Swift generic type arguments. (no canonical witness for Intent)

AppIntentRecommendation.init(intent:description:)

This declaration needs Swift generic type arguments. (no canonical witness for Intent)

AppIntentRecommendation.init(intent:description:)

This declaration needs Swift generic type arguments. (no canonical witness for Intent)

AppIntentRecommendation.init(intent:description:)

This declaration needs Swift generic type arguments. (no canonical witness for Intent)

AppIntentConfiguration.init(kind:intent:provider:content:)

This declaration needs Swift generic type arguments. (no canonical witness for Provider)

WidgetInfo.widgetConfigurationIntent(of:)

This declaration needs Swift generic type arguments. (no canonical witness for Intent)

StaticConfiguration.body

This protocol needs associated types that cannot yet cross the bridge.

StaticConfiguration.init(kind:provider:content:)

This declaration needs Swift generic type arguments. (no canonical witness for Provider)

ControlInfo.configurationIntent(of:)

This declaration needs Swift generic type arguments. (no canonical witness for Intent)

ActivityViewContext.attributes

This declaration needs Swift generic type arguments. (no canonical witness for Attributes)

ActivityViewContext.state

This declaration needs Swift generic type arguments. (no canonical witness for Attributes.ContentState)

DynamicIsland.init(expanded:compactLeading:compactTrailing:minimal:)

callback cannot propagate synchronous failure

WidgetRelevanceAttribute.init(configuration:context:)

This declaration needs Swift generic type arguments. (no canonical witness for Configuration)

WidgetRelevanceAttribute.init(configuration:group:)

This declaration needs Swift generic type arguments. (no canonical witness for Configuration)

ActivityConfiguration.init(for:content:dynamicIsland:)

Passing a Swift type itself is not supported.

ActivityConfiguration.body

This protocol needs associated types that cannot yet cross the bridge.

DynamicIslandExpandedContentBuilder.buildPartialBlock(first:)

This protocol needs associated types that cannot yet cross the bridge.

DynamicIslandExpandedContentBuilder.buildPartialBlock(first:)

This protocol needs associated types that cannot yet cross the bridge.

DynamicIslandExpandedContentBuilder.buildPartialBlock(accumulated:next:)

This protocol needs associated types that cannot yet cross the bridge.

DynamicIslandExpandedContentBuilder.buildPartialBlock(accumulated:next:)

This protocol needs associated types that cannot yet cross the bridge.

AppIntentControlConfiguration.body

This protocol needs associated types that cannot yet cross the bridge.

AppIntentControlConfiguration.init(kind:provider:content:)

This declaration needs Swift generic type arguments. (no canonical witness for Provider)

AppIntentControlConfiguration.init(kind:intent:content:)

This declaration needs Swift generic type arguments. (no canonical witness for Configuration)

WidgetPreviewContext.subscript(_:)

Passing a Swift type itself is not supported.

AccessoryWidgetBackground.body

This protocol needs associated types that cannot yet cross the bridge.

PreviewTimelineBuilder.buildExpression(_:)

This parameter hides a concrete Swift type.

DynamicIslandExpandedRegion.init(_:priority:content:)

callback cannot propagate synchronous failure

IntentTimelineProvider.recommendations()

The iOS SDK compiler rejected this binding: member 'recommendations' cannot be used on value of type 'any IntentTimelineProvider'; consider using a generic constraint instead [#ExistentialMemberAccess]

IntentTimelineProvider.relevance()

The iOS SDK compiler rejected this binding: member 'relevance' cannot be used on value of type 'any IntentTimelineProvider'; consider using a generic constraint instead [#ExistentialMemberAccess]