8. Introduction to Complications

Written by Scott Grosch

When you design an iOS app, it’s normal to expect users will engage with your app for some time. On the other hand, when designing a watchOS app, you’ll likely find users engage with the app for mere seconds. Therefore, you should always strive to add complications to your app.

Wait, what? Not that kind of complication — a watch complication. According to Wikipedia:

A complication is any feature of a mechanical timepiece beyond the display of hours, minutes and seconds.

By that definition, the Apple Watch is full of complications! :]

On the Apple Watch, complications have been slightly redefined as elements on the watch face that display small, immediately relevant bits of information. They are by far one of the most compelling and useful features of the Apple Watch. They lie right on the watch face, making accessing information as fast as raising your wrist.

This chapter will speak to a high-level overview of what complications are and why you should use them. The following chapters will dive into the technical details of actually implementing them.

Unless there’s a compelling reason not to include one, every watchOS app should include at least one complication.

Why complications?

As previously mentioned, interacting with a watchOS app is generally on the order of a second or two, if even that long. For example, when using a mapping app, you probably just want to know how far away your next turn is and which direction you’ll be heading.

Even if you don’t feel that your app contains any data which would make sense to display on the watch face, providing a complication gives your user a way to launch your app with a simple touch of the screen. On top of that, watchOS provides several benefits when your user includes your complication on their watch face:

• watchOS keeps your app in memory and gives it extra update time, making app launches almost instantaneous.
• You complication can receive up to 50 pushes per day containing updated information.
• Your app can perform additional background refresh tasks.
• Your complication can be featured in the Apple Watch Face Gallery on the phone.

Imagine the types of questions you can instantly answer by having a complication available on the watch face:

• What’s the score?
• How hot is it outside?
• Is the air safe to breathe?
• What is your name?
• What is your quest?
• What is the average airspeed velocity of an unladen swallow?

Note: If you’re confused by the last three questions, they’re from a famous scene in the 1975 movie Monty Python and the Holy Grail. The internet seems to think a swallow would average around 20 miles per hour or about 9 meters per second.

Recent versions of iOS provide a similar concept via Widgets. However, unlike the Apple Watch, to see the data on a widget, you’ll need to pull the phone out of your pocket or purse, unlock the screen, possibly swipe to another screen and then see your data. Complications are quicker.

The following chapters will dive into the technical details of using the ClockKit framework to implement complications and show how to keep them up-to-date with current information.

In other words, by providing complications, you’ll uncomplicate your app. :]

Complication families

If you’ve spent any time looking at the Apple Watch’s available watch faces, you’ve seen that there are quite a few. Each new release of watchOS tends to include more faces than the previous version.

Beyond the layout of the watch face, each separate face provides different types of complications. Apple groups the types of complications displayed into families, represented by the CLKComplicationFamily enumeration type.

There are currently 12 different families which you should implement. Each family contains a distinct set of templates that you can apply to complications of that specific family. Support all of the complication families to provide the best user experience. That snazzy Utilitarian watch face you’re using might be your favorite, but your customer might prefer a completely different watch face.

Complication identifiers

Most watch faces include the ability to specify multiple complications. While most apps only provide a single complication, ideally supporting all families, you can support more than one. If you’ve created a weather app, you might provide one complication which shows the temperature and a separate complication that displays the current air quality index.

All complications you support are created via the CLKComplicationDescriptor(identifier:displayName:supportedFamilies:) initializer. Including a unique identifier lets you provide multiple versions of the same complication family.

Complication templates

Within each family, Apple provides multiple templates which describe the layout of the complication. Most of the templates consist of simple text and images, though some provide partial SwiftUI View support.

Circular small

The Circular Small template provides a small circle in the corners of the Color watch face that can display a few characters of text, an image or a circular progress ring. It includes the following templates:

Image templates

• CLKComplicationTemplateCircularSmallRingImage: A single image with a progress ring.

• CLKComplicationTemplateCircularSmallSimpleImage: A single image with no text.

• CLKComplicationTemplateCircularSmallStackImage: An image with a line of text below it.

Text templates

• CLKComplicationTemplateCircularSmallRingText: A short text string inside of a progress ring.

• CLKComplicationTemplateCircularSmallSimpleText: A short text string with no image.

• CLKComplicationTemplateCircularSmallStackText : Two short text strings, one atop the other.

Extra-large

The extra-large templates are similar to the Circular Small templates but larger and with a 2x2 grid template. They’re designed for the X-Large watch face.

Image templates

• CLKComplicationTemplateExtraLargeRingImage: A single image with a progress ring.

• CLKComplicationTemplateExtraLargeSimpleImage: A single image with no text.

• CLKComplicationTemplateExtraLargeStackImage: An image with a line of text below it.

Text templates

• CLKComplicationTemplateExtraLargeColumnsText: A 2x2 grid of text.

• CLKComplicationTemplateExtraLargeRingText: A short text string inside of a progress ring.

• CLKComplicationTemplateExtraLargeSimpleText: A short text string with no image.

• CLKComplicationTemplateExtraLargeStackText: Two short text strings, one atop the other.

Modular small

When using the Modular watch face, you can provide content to the smaller spaces via these templates.

Image templates

• CLKComplicationTemplateModularSmallRingImage: A single image with a progress ring.

• CLKComplicationTemplateModularSmallSimpleImage: A single image.

• CLKComplicationTemplateModularSmallStackImage: An image with a line of text below it.

Text templates

• CLKComplicationTemplateModularSmallColumnsText: A 2x2 grid of text.

• CLKComplicationTemplateModularSmallRingText : A short text string inside of a progress ring.

• CLKComplicationTemplateModularSmallSimpleText: A short text string with no image.

• CLKComplicationTemplateModularSmallStackText: Two short text strings, one atop the other.

Modular large

The modular large templates target the large canvas on the Modular watch face, providing up to three lines of content.

Body templates

• CLKComplicationTemplateModularLargeStandardBody: Displays a header row and two lines of text.

• CLKComplicationTemplateModularLargeTallBody: Displays a header row and a single tall line of text.

Table templates

• CLKComplicationTemplateModularLargeColumns: Displays either a 3x2 grid of text or a 3x3 grid where the first column is a small image.

• CLKComplicationTemplateModularLargeTable: Displays a header row with an optional small image, and then a 2x2 grid of text.

Utilitarian

The utilitarian templates provide multiple ways to display content on numerous watch faces, including Utility, Chronograph, Simple and the character watch faces.

Utilitarian small

• CLKComplicationTemplateUtilitarianSmallFlat: Displays an image followed by short text on a single line.

• CLKComplicationTemplateUtilitarianSmallRingImage: Displays a small image inside of a circular progress ring.

• CLKComplicationTemplateUtilitarianSmallRingText: Displays a short text string inside of a circular progress ring.

• CLKComplicationTemplateUtilitarianSmallSquare: Displays a small square image.

Utilitarian large

• CLKComplicationTemplateUtilitarianLargeFlat: Displays an image followed by a long text string on a single line.

Graphic

The graphic templates display visually rich content on several different watch faces, including the Infograph, Infograph Modular and Solari Dial faces.

Unlike the other templates, the graphic templates also let you use SwiftUI views in place of rigid layouts. There are almost 30 different templates in the graphic family, which is too many to enumerate here. The following chapters will speak directly to using SwiftUI in your complications.

The graphic templates fall into five families:

• CLKComplicationFamily.graphicCorner: The curved areas that fill the corners of the Infograph watch face.

• CLKComplicationFamily.graphicCircular: The circular areas on the Infograph and Infograph Modular watch faces.

• CLKComplicationFamily.graphicBezel: A circular area with optional curved text along the bezel of the Infograph watch face.

• CLKComplicationFamily.graphicRectangular: The large rectangular area in the center of the Infograph Modular watch face.

• CLKComplicationFamily.graphicExtraLarge: A large square area on the X-Large watch face.

Tinted complications

While you can include full-color images in many complication templates, you need to be careful not to make your complication depend on those colors being visible.

One reason, of course, is that many people are color blind. The Colour Blind Awareness organization estimates that approximately one in twelve men and one in 200 women globally are color blind.

From a purely technical standpoint, your users can disable the colors! Watch faces that support graphic complications can be tinted, displaying a low-color version of the complication. If the watch face is tinted, the following changes apply to the template:

• Gauges which previously used a color gradient now display a solid color based on the selected tint.
• Text color is based on the user’s watch face color, while multicolor text providers display a single color.
• Images are desaturated by default though you can provide a custom tinted version for the image.

Key points

• Always provide a complication, even if just to provide a quick way to launch your app.
• Support every complication family, not just one or two.
• Consider the different pieces of data someone might want to regularly see on the watch face and create a complication for each one.

Where to go from here?

• Apple’s documentation on ClockKit shows images of exactly where each type of complication displays on the watch face, as well as examples of each template type.