Adding a Complication to Your watchOS App

Build a better watchOS experience using complications.


Complications are small elements that display essential information right on the watch face. The system provides built-in complications for weather, calendar, activity tracking, and more, and users can select the complications they want to see on their watch face.

The system sets the size and placement of the complication, based on the selected watch face. Figure 1 shows the layout of the Modular watch face, which has space for five different complications: one large and four small.

Figure 1

The complications on the Modular watch face

An illustration showing the space for one large and four small complications on the Modular watch face.

Improve Your App with Complications

Complications represent an important part of your apps user interface, displaying content and adding interactivity. You should strongly consider creating complications for your app, even if they only act as a launcher for your watchOS app. A complication on the active watch face provides:

  • Vital information when the user glances at their watch.

  • The ability to rapidly wake your app when the user taps on the complication.

  • The ability to perform background tasks, keeping your complication and app up to date.

When your app has a complication on the active watch face, watchOS tries to keep your watch app suspended in memory. The system can wake your app from the background quickly when the user wants to interact with it.

The system also provides apps with active complications larger budgets for background refresh tasks. You can use these background tasks to keep the content of your watchOS app and your complications up to date and accurate.

Enable Complications in Your App

The easiest way to enable complications is to check Include Complications when creating a new watchOS app (Figure 2).

Figure 2

Include complications when creating a watchOS project

The option sheet with the Include Complications option enabled.

When you include complications, Xcode creates and configures a complication data source for your app. It also declares support for all the available complication families. If your app only supports a subset of these families, open your WatchKit Extension’s General tab and deselect the unsupported families (see Figure 3).

Figure 3

Set the selected complication families

A screenshot of the WatchKit extension’s General tab showing the Complication Configuration settings.

To add complications to an existing watchOS app, create a class that adopts the CLKComplicationDataSource protocol. Next, open the Complication Configurations and set the Data Source Class to your class. Then check all the complication families that your app supports.

After you’ve enabled the complications, you still need to implement your datasource and add placeholders for your complications. For more information, see Providing Data for Your Complication and Adding Placeholders for Your Complication.


Implement the Complication

Providing Data for Your Complication

Implement the data source methods to load your complication’s timeline entries.

Adding Placeholders for Your Complication

Provide the placeholders that users see when adding your complication to a watch face.

See Also



A protocol that communicates with ClockKit, providing information about your complication.