<!--
{
  "availability" : [
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "ClockKit",
  "identifier" : "/documentation/ClockKit/CLKComplicationDataSource",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "ClockKit"
    ],
    "preciseIdentifier" : "c:objc(pl)CLKComplicationDataSource"
  },
  "title" : "CLKComplicationDataSource"
}
-->

# CLKComplicationDataSource

A protocol that provides ClockKit with information about your complication.

```
@MainActor protocol CLKComplicationDataSource : NSObjectProtocol
```

## Overview

Apps that support a complication must define a class that supports the [`CLKComplicationDataSource`](/documentation/ClockKit/CLKComplicationDataSource) protocol and register it with the system. Your data source is responsible for providing timeline entries and data for all of the complication families that you support. You do this by implementing the protocol methods, returning the timeline entries displayed by your complication and information about the features that your complication supports.

You don’t instantiate your data source class explicitly. After defining your class, specify the class name in the General tab of the project settings for your WatchKit extension. When the system needs data, ClockKit instantiates your data source and initializes it by calling its `init` method. Once initialized, ClockKit calls the corresponding protocol methods to gather any needed data. You can also specify your class name in your app’s `Info.plist` file using the `CLKComplicationsPrincipalClass` key.

When the user installs your complication on the clock face, ClockKit creates an appropriate [`CLKComplication`](/documentation/ClockKit/CLKComplication) object for the selected complication family. ClockKit then passes the complication to your data source so that you know how to format your timeline entries. Use the General tab of your WatchKit extension’s project settings to specify the families you support.

Your complication data source class must implement the [`CLKComplicationDataSource`](/documentation/ClockKit/CLKComplicationDataSource) protocol’s [`getCurrentTimelineEntry(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getCurrentTimelineEntry(for:withHandler:)) method.

You may implement other methods as needed to support the data in your complication. For example, to batch load future timeline entries, implement [`getTimelineEndDate(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineEndDate(for:withHandler:)) and pass a future date to the handler. For more information, see [Creating complications for your watchOS app](/documentation/ClockKit/creating-complications-for-your-watchos-app).

> Note:
> For watchOS 6 and earlier, you must implement both ``doc://com.apple.clockkit/documentation/ClockKit/CLKComplicationDataSource/getCurrentTimelineEntry(for:withHandler:)`` and ``doc://com.apple.clockkit/documentation/ClockKit/CLKComplicationDataSource/getSupportedTimeTravelDirections(for:withHandler:)``. Use ``doc://com.apple.clockkit/documentation/ClockKit/CLKComplicationDataSource/getSupportedTimeTravelDirections(for:withHandler:)`` to specify whether your app can batch load future timeline entries.

ClockKit calls your data source methods on your watchOS app’s main thread.

## Topics

### Migrating to WidgetKit

[`var widgetMigrator: any CLKComplicationWidgetMigrator`](/documentation/ClockKit/CLKComplicationDataSource/widgetMigrator)

A migrator that maps ClockKit complications to their WidgetKit replacements.

[`class CLKComplicationStaticWidgetMigrationConfiguration`](/documentation/ClockKit/CLKComplicationStaticWidgetMigrationConfiguration)

A configuration object that specifies a static complication in WidgetKit.

[`class CLKComplicationAppIntentWidgetMigrationConfiguration`](/documentation/ClockKit/CLKComplicationAppIntentWidgetMigrationConfiguration)

A configuration object that specifies a WidgetKit complication that uses app intents.

[`class CLKComplicationIntentWidgetMigrationConfiguration`](/documentation/ClockKit/CLKComplicationIntentWidgetMigrationConfiguration)

A configuration object that specifies an intents-based complication in WidgetKit.

[`protocol CLKComplicationWidgetMigrator`](/documentation/ClockKit/CLKComplicationWidgetMigrator)

A protocol that maps ClockKit complications to their WidgetKit replacements.

[`class CLKComplicationWidgetMigrationConfiguration`](/documentation/ClockKit/CLKComplicationWidgetMigrationConfiguration)

An abstract class that specifies WidgetKit complications.

### Setting information property keys

  <doc://com.apple.documentation/documentation/BundleResources/Information-Property-List/CLKComplicationPrincipalClass>

### Deprecated methods

[`let CLKLaunchedTimelineEntryDateKey: String`](/documentation/ClockKit/CLKLaunchedTimelineEntryDateKey)

A key that indicates the date when the system launched the complication.

[`let CLKLaunchedComplicationIdentifierKey: String`](/documentation/ClockKit/CLKLaunchedComplicationIdentifierKey)

A key that indicates the identifier of a complication the system launched.

[`func getComplicationDescriptors(handler: ([CLKComplicationDescriptor]) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getComplicationDescriptors(handler:))

Returns the list of complication descriptors.

[`func handleSharedComplicationDescriptors([CLKComplicationDescriptor])`](/documentation/ClockKit/CLKComplicationDataSource/handleSharedComplicationDescriptors(_:))

Informs the app about complications from a shared watch face.

[`func getLocalizableSampleTemplate(for: CLKComplication, withHandler: (CLKComplicationTemplate?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getLocalizableSampleTemplate(for:withHandler:))

Gets a localizable template that shows sample data for the specified complication.

[`func getPrivacyBehavior(for: CLKComplication, withHandler: (CLKComplicationPrivacyBehavior) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getPrivacyBehavior(for:withHandler:))

Returns the privacy behavior for the specified complication.

[`enum CLKComplicationPrivacyBehavior`](/documentation/ClockKit/CLKComplicationPrivacyBehavior)

Constants indicating the complication behavior when the Apple Watch is locked.

[`func getAlwaysOnTemplate(for: CLKComplication, withHandler: (CLKComplicationTemplate?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getAlwaysOnTemplate(for:withHandler:))

Returns the template to use during Always On.

[`func getTimelineEndDate(for: CLKComplication, withHandler: (Date?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineEndDate(for:withHandler:))

Retrieves the last date for the data that your app can supply.

[`func getCurrentTimelineEntry(for: CLKComplication, withHandler: (CLKComplicationTimelineEntry?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getCurrentTimelineEntry(for:withHandler:))

Retrieves the timeline entry that you want to display now.

[`func getTimelineEntries(for: CLKComplication, after: Date, limit: Int, withHandler: ([CLKComplicationTimelineEntry]?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineEntries(for:after:limit:withHandler:))

Retrieves future timeline entries for the complication.

[`func getTimelineAnimationBehavior(for: CLKComplication, withHandler: (CLKComplicationTimelineAnimationBehavior) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineAnimationBehavior(for:withHandler:))

Gets the animation behavior when transitioning between timeline entries.

[`enum CLKComplicationTimelineAnimationBehavior`](/documentation/ClockKit/CLKComplicationTimelineAnimationBehavior)

Constants indicating the animation behavior during Time Travel.

[`func getSupportedTimeTravelDirections(for: CLKComplication, withHandler: (CLKComplicationTimeTravelDirections) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getSupportedTimeTravelDirections(for:withHandler:))

Determines whether your complication can provide timeline entries for the future or the past.

[`struct CLKComplicationTimeTravelDirections`](/documentation/ClockKit/CLKComplicationTimeTravelDirections)

Constants indicating the supported time travel directions, if any.

[`func getTimelineStartDate(for: CLKComplication, withHandler: (Date?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineStartDate(for:withHandler:))

Retrieves the earliest date for which your complication is prepared to supply data.

[`func getTimelineEntries(for: CLKComplication, before: Date, limit: Int, withHandler: ([CLKComplicationTimelineEntry]?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineEntries(for:before:limit:withHandler:))

Retrieves past timeline entries for the complication.

[`func getNextRequestedUpdateDate(handler: (Date?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getNextRequestedUpdateDate(handler:))

Gets the next time at which to update your complication.

[`func requestedUpdateDidBegin()`](/documentation/ClockKit/CLKComplicationDataSource/requestedUpdateDidBegin())

Indicates that a requested update has begun so that you’ve an opportunity to extend or reload your timeline.

[`func requestedUpdateBudgetExhausted()`](/documentation/ClockKit/CLKComplicationDataSource/requestedUpdateBudgetExhausted())

Indicates that your complication’s time budget is exhausted.

[`func getPlaceholderTemplate(for: CLKComplication, withHandler: (CLKComplicationTemplate?) -> Void)`](/documentation/ClockKit/CLKComplicationDataSource/getPlaceholderTemplate(for:withHandler:))

Gets a static template to display in the selection screen for your complication.

## Relationships

### Inherits From

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

---

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)