<!--
{
  "availability" : [
    "iOS: 17.0.0 -",
    "iPadOS: 17.0.0 -",
    "macCatalyst: -",
    "macOS: 14.0.0 -",
    "visionOS: 26.0.0 -",
    "watchOS: 10.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "WidgetKit",
  "identifier" : "/documentation/WidgetKit/AppIntentTimelineProvider",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "WidgetKit"
    ],
    "preciseIdentifier" : "s:9WidgetKit25AppIntentTimelineProviderP"
  },
  "title" : "AppIntentTimelineProvider"
}
-->

# AppIntentTimelineProvider

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

```
protocol AppIntentTimelineProvider
```

## Overview

An App Intent timeline provider performs the same function as
[`TimelineProvider`](/documentation/WidgetKit/TimelineProvider), but it also incorporates user-configured details
into timeline entries.

For example, in a widget that displays the health status of a game
character the user has chosen, the provider receives a custom
intent specifying the character to display. In your app code,
you then define a custom App Intent. The intent
can include the character’s details such as its name,
avatar, strategic alliances, and so on.

```
struct CharacterConfiguration: WidgetConfigurationIntent {
    static var title: LocalizedStringResource = "Character"

    @Parameter(title: "Name")
    var name: String

    @Parameter(title: "Avatar", default: "Player 1")
    var avatar: String

    @Parameter(title: "Alliances", default: [])
    var alliances: [String]

    @Parameter(title: "Health", default: 100.0)
    var healthLevel: Double
}
```

Because users can add multiple instances of a particular widget, your
provider needs a way to differentiate which instance WidgetKit is asking
about. When WidgetKit calls
[`snapshot(for:in:)`](/documentation/WidgetKit/AppIntentTimelineProvider/snapshot(for:in:)) or
[`timeline(for:in:)`](/documentation/WidgetKit/AppIntentTimelineProvider/timeline(for:in:)), it passes an
instance of your configuration intent, configured with the user-selected
details. The game widget provider accesses the properties of the intent and
includes them in the [`TimelineEntry`](/documentation/WidgetKit/TimelineEntry). WidgetKit then invokes the widget
configuration’s content closure, passing the timeline entry to allow the
views to access the user-configured properties. For example, the provider
might implement a `TimelineEntry` with properties corresponding to those in
the custom intent:

```
struct CharacterDetailEntry: TimelineEntry {
    var date: Date
    var name: String
    var avatar: String
    var alliances: [String]
    var healthLevel: Double
}
```

To generate a snapshot, the game widget provider initializes the character
detail entry using the properties from the intent.

```
struct CharacterDetailProvider: AppIntentTimelineProvider {
    func snapshot(for configuration: CharacterConfiguration, in context: Context) async -> CharacterDetailEntry {
        return CharacterDetailEntry(
            date: Date(),
            name: configuration.characterName,
            avatar: configuration.avatar,
            alliances: configuration.alliances,
            healthLevel: configuration.healthLevel?.doubleValue
        )
    }
}
```

## Topics

### Generating timelines

[`placeholder(in:)`](/documentation/WidgetKit/AppIntentTimelineProvider/placeholder(in:))

Provides a timeline entry representing a placeholder version of the
widget.

[`recommendations()`](/documentation/WidgetKit/AppIntentTimelineProvider/recommendations())

Returns a set of intent recommendations you use to offer pre-configured
widgets on platforms that don’t offer a dedicated user interface for
customizing widget intents.

[`relevance()`](/documentation/WidgetKit/AppIntentTimelineProvider/relevance())

Provides an object containing attributes that describe when a specific
widget is relevant.

[`snapshot(for:in:)`](/documentation/WidgetKit/AppIntentTimelineProvider/snapshot(for:in:))

Provides a timeline entry representing the current time and state of a
widget.

[`timeline(for:in:)`](/documentation/WidgetKit/AppIntentTimelineProvider/timeline(for:in:))

Provides an array of timeline entries for the current time and,
optionally, any future times to update a widget.

[`AppIntentTimelineProvider.Context`](/documentation/WidgetKit/AppIntentTimelineProvider/Context)

An object that contains details about how a widget is rendered, including its size and whether it
appears in the widget gallery.

[`Entry`](/documentation/WidgetKit/AppIntentTimelineProvider/Entry)

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

[`Intent`](/documentation/WidgetKit/AppIntentTimelineProvider/Intent)

The intent that contains user-customized values.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)