<!--
{
  "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

[`widgetMigrator`](/documentation/ClockKit/CLKComplicationDataSource/widgetMigrator)

A migrator that maps ClockKit complications to their WidgetKit replacements.

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

A configuration object that specifies a static complication in WidgetKit.

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

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

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

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

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

A protocol that maps ClockKit complications to their WidgetKit replacements.

[`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

[`CLKLaunchedTimelineEntryDateKey`](/documentation/ClockKit/CLKLaunchedTimelineEntryDateKey)

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

[`CLKLaunchedComplicationIdentifierKey`](/documentation/ClockKit/CLKLaunchedComplicationIdentifierKey)

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

[`getComplicationDescriptors(handler:)`](/documentation/ClockKit/CLKComplicationDataSource/getComplicationDescriptors(handler:))

Returns the list of complication descriptors.

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

Informs the app about complications from a shared watch face.

[`getLocalizableSampleTemplate(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getLocalizableSampleTemplate(for:withHandler:))

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

[`getPrivacyBehavior(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getPrivacyBehavior(for:withHandler:))

Returns the privacy behavior for the specified complication.

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

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

[`getAlwaysOnTemplate(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getAlwaysOnTemplate(for:withHandler:))

Returns the template to use during Always On.

[`getTimelineEndDate(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineEndDate(for:withHandler:))

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

[`getCurrentTimelineEntry(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getCurrentTimelineEntry(for:withHandler:))

Retrieves the timeline entry that you want to display now.

[`getTimelineEntries(for:after:limit:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineEntries(for:after:limit:withHandler:))

Retrieves future timeline entries for the complication.

[`getTimelineAnimationBehavior(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineAnimationBehavior(for:withHandler:))

Gets the animation behavior when transitioning between timeline entries.

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

Constants indicating the animation behavior during Time Travel.

[`getSupportedTimeTravelDirections(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getSupportedTimeTravelDirections(for:withHandler:))

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

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

Constants indicating the supported time travel directions, if any.

[`getTimelineStartDate(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineStartDate(for:withHandler:))

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

[`getTimelineEntries(for:before:limit:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getTimelineEntries(for:before:limit:withHandler:))

Retrieves past timeline entries for the complication.

[`getNextRequestedUpdateDate(handler:)`](/documentation/ClockKit/CLKComplicationDataSource/getNextRequestedUpdateDate(handler:))

Gets the next time at which to update your complication.

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

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

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

Indicates that your complication’s time budget is exhausted.

[`getPlaceholderTemplate(for:withHandler:)`](/documentation/ClockKit/CLKComplicationDataSource/getPlaceholderTemplate(for:withHandler:))

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


---

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)