# Creating a timeline entry Package your app-specific data into a template and create a timeline entry for that template. ## Discussion ClockKit periodically requests timeline entries from your complication’s data source. A timeline entry consists of a complication template that you have configured with your app’s data and a date that specifies when ClockKit displays that template.  Your data source packages app-specific data into a template that ClockKit can display onscreen. To create the template, you examine the provided [`CLKComplication`](/documentation/ClockKit/CLKComplication) object, select an appropriate template, fill the template with data from your app, and then create a timeline entry for the template. ### Examine the Complication Object When ClockKit requests a template, it always provides a [`CLKComplication`](/documentation/ClockKit/CLKComplication) object that describes the complication. The complication has an [`identifier`](/documentation/ClockKit/CLKComplication/identifier) that your app defines, and a [`family`](/documentation/ClockKit/CLKComplication/family) from the [`CLKComplicationFamily`](/documentation/ClockKit/CLKComplicationFamily) enumeration. Each [`identifier`](/documentation/ClockKit/CLKComplication/identifier) defines a separate complication type for the specified [`family`](/documentation/ClockKit/CLKComplication/family). Examine the [`identifier`](/documentation/ClockKit/CLKComplication/identifier) to determine which kind of complication you’re creating. In watchOS 7 and later, your app can provide one or more complications per [`family`](/documentation/ClockKit/CLKComplication/family). For example, a weather app may support separate complications for the `Condition`, `Temperature`, and `Precipitation` identifiers. ```swift switch complication.identifier { case complicationConditionIdentifier: templateOrNil = myGetConditionTemplate(for: family, date: date) case complicationTemperatureIdentifier: templateOrNil = myGetTemperatureTemplate(for: family, date: date) case complicationPrecipitationIdentifier: templateOrNil = myGetPrecipitationPercentageTemplate(for: family, date: date) ``` The ClockKit framework organizes complications into families. Each family defines the size and shape of the complication. Examine the [`family`](/documentation/ClockKit/CLKComplication/family) to discover which kind of template you can use. For the complete list of families, see [`CLKComplicationFamily`](/documentation/ClockKit/CLKComplicationFamily). ```swift switch complication.family { case .circularSmall: // Create a template from the circular small family. case .modularSmall: // Create a template from the modular small family. case .modularLarge: // Create a template from the modular large family. // Continue with all the templates supported by the specified type. @unknown default: print("*** Unknown Complication Family: \(complication.family) ***") // Handle the error here. } ``` Each family provides one or more templates that define the type of data and the data’s position within the complication. Select and create a template for the specified family from the following pages: - [Circular small](/documentation/ClockKit/circular-small) - [Extra large](/documentation/ClockKit/extra-large) - [Modular small](/documentation/ClockKit/modular-small) - [Modular large](/documentation/ClockKit/modular-large) - [Utilitarian](/documentation/ClockKit/utilitarian) - [Graphic](/documentation/ClockKit/graphic) > Note: > For watchOS 6 and earlier, your app can provide only one complication per family. To support these versions of watchOS, you only need to check the complication’s ``doc://com.apple.clockkit/documentation/ClockKit/CLKComplication/family`` property when determining which template to use. ### Create Data Providers to Fill the Template Data providers take a raw value and format it for the template. For example, the [`CLKSimpleTextProvider`](/documentation/ClockKit/CLKSimpleTextProvider) takes two strings—a short string and a long string. If you provide both, ClockKit selects the best string for the template’s size. ```swift let temperature = myCity.temperature(date) let nameProvider = CLKSimpleTextProvider( text: myCity.name, shortText: myCity.abbreviation) let temperatureProvider = CLKSimpleTextProvider( text: "\(longNumberFormatter.string(from: NSNumber(value: temperature)) ?? "Unknown")º F", shortText: shortNumberFormatter.string(from: NSNumber(value: temperature)) ?? "??") ``` ClockKit uses data providers for text, images, and gauges, including: - [`CLKSimpleTextProvider`](/documentation/ClockKit/CLKSimpleTextProvider) - [`CLKDateTextProvider`](/documentation/ClockKit/CLKDateTextProvider) - [`CLKTimeTextProvider`](/documentation/ClockKit/CLKTimeTextProvider) - [`CLKRelativeDateTextProvider`](/documentation/ClockKit/CLKRelativeDateTextProvider) - [`CLKTimeIntervalTextProvider`](/documentation/ClockKit/CLKTimeIntervalTextProvider) - [`CLKImageProvider`](/documentation/ClockKit/CLKImageProvider) - [`CLKFullColorImageProvider`](/documentation/ClockKit/CLKFullColorImageProvider) - [`CLKSimpleGaugeProvider`](/documentation/ClockKit/CLKSimpleGaugeProvider) - [`CLKTimeIntervalGaugeProvider`](/documentation/ClockKit/CLKTimeIntervalGaugeProvider) Some of the data providers, like [`CLKRelativeDateTextProvider`](/documentation/ClockKit/CLKRelativeDateTextProvider) and [`CLKTimeIntervalGaugeProvider`](/documentation/ClockKit/CLKTimeIntervalGaugeProvider), automatically update the complication as time passes without affecting your complication’s background execution budgets. Use the data providers to create and populate your template. ```swift let template = CLKComplicationTemplateModularSmallStackText( line1TextProvider: temperatureProvider, line2TextProvider: nameProvider) ``` ### Use Complication Data The [`CLKComplicationDescriptor`](/documentation/ClockKit/CLKComplicationDescriptor) class’s `userInfo` and `userActivity` properties let you pass additional data about the complication. You can use this data to simplify creating timeline entires, and to launch a particular scene in your app. For example, you can create a set of complications from the user’s favorite city list, as shown in [Dynamically Define Descriptors](/documentation/ClockKit/declaring-complications-for-your-app#Dynamically-Define-Descriptors). Instead of parsing the complications identifier, you can add the city and the weather data type to the complication’s [`userInfo`](/documentation/ClockKit/CLKComplication/userInfo) dictionary. Then, to create a timeline entry, you read the data from the dictionary before selecting and filling your template. ```swift let city: City // Read the city id from the complication's userInfo dictionary. if let cityID = complication.userInfo?[myCityIDKey] as? String { city = myData.lookupCity(byID: cityID) ?? myData.currentCity } else { city = myData.currentCity } let nameProvider = CLKSimpleTextProvider( text: city.name, shortText: city.abbreviation) // Read the complication type from the userInfo dictionary. let typeIdentifier = complication.userInfo?[myTypeIdentifierKey] as? String ?? "Undefined" ``` ### Create the Timeline Entry Object Create a [`CLKComplicationTimelineEntry`](/documentation/ClockKit/CLKComplicationTimelineEntry) object using the template and the desired date. For the current timeline entry, you must specify a date equal to or earlier than the current time. ```swift CLKComplicationTimelineEntry(date: Date(), complicationTemplate: template) ``` For future timeline entries, specify the date and time for the data to appear on the complication. For a meeting complication, you might display information about a meeting before its scheduled start time. For more information on creating future timeline entries, see [Loading future timeline events](/documentation/ClockKit/loading-future-timeline-events). ## See Also [Enabling Complications for Your watchOS App](/documentation/ClockKit/enabling-complications-for-your-watchos-app) Set up your watchOS app’s complications. [Adding Placeholders for Your Complication](/documentation/ClockKit/adding-placeholders-for-your-complication) Provide the placeholders that users see when adding your complication to a watch face. --- Copyright © 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)