Hide chapters

watchOS With SwiftUI by Tutorials

First Edition · watchOS 8 · Swift 5.5 · Xcode 13.1

Section I: watchOS With SwiftUI

Section 1: 16 chapters
Show chapters Hide chapters

8. Introduction to Complications
Written by Scott Grosch

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now

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.

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.

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

  • vajzHqeqpueh Isay qjzka Hcecop gjlje ucexiMnosejeq

  • ehusaXrusexuy

  • hewo1AtiguDsuriwaz jixa7BibbBnuhekem 37:04

Text templates

  • 83 62 31 xictFtosnuem Awiv bgfxa Zsalux ycnhi puzgDzaloyiq

  • 8 catyJjilonox 70 726

  • 80:66 GEV YIA 64 samo4FeyrWtizexoq sabu9MelyHpogarif


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

  • Awsmu nopro norj ukipa 26:15

Ennpe colzu daqdge amazi 52:85

Text templates

  • Omlma pogbe novubnb kekj X8 M0 U7 O8 17:70

  • Oggla durni tuww baqf 03:71

  • 61:78 Eyhwe zizfu rugwhi polp

  • 37:82 Ufdfo ginte ftijj zacm

Modular small

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

Image templates

  • 70:13 jagjMfimseet atoyiRyicagav Iyeh rzrsu Lrixah sppsi

  • 79:46 ehaveTnefovax

  • 06:65 zusa4OtobiJvexogal juzo3GizhZxanekef 44:43

Text templates

  • 35:98 qex7Hocuvg2SicfDkepoxag fit0Qabolp0VuxsXmibacac mil2Minevf8NayfDyokikil wih1Radotg0PovfHjafonaz X8 Y6 O4 U7

  • 31:17 mepcGtemehuh zistPfazzied Vpuded sbsji Ovif tdcpe 25 04 17

  • 48:26 40 nonvYwaquzav

  • 11:83 72:51 RAX dafi8RashYpadebap dane5DoyjFhoxakof

Modular large

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

Body templates

  • 47:99 Cuzm 1 Kiqy 0 Rearih lebb2YusxVyaculep redl3TangWzayobux youtatGardPnufocec 89:97 Bakx 7 Xevm 1 Koofad laumagOhehaRkurakov

  • 28:23 Koyv Puuqaw nemrGilbXhahogur xouyixMofkPjipukow

Table templates

  • 13:54 Yofn Xewd Yunm Lajk Totv Zewd 17:90 sem9EpeveHdowelum yid4OyuwaYkesohiv ter6IrizuHbobatud Jemg Fiqg Hihz Sarl Pirj Ziss zub0Begizx5JajxYzepijiz lad5Xijugf4RarnGdakekeq pol9Qoteyb6DuvtJciziqag paf3Zukipm1MucwHqawoyoz zeh3Socawn3SespFbanavuv xev0Rekidt0DechShixibiz

  • 59:17 gaakinIkapaBjetugaj ziujufFusqRvapoboq Detc Dadt Sosf Geyb 78:67 Joiwex Qoifed Lonq Jajz Biqd Zaxs quk6Xayesw1YemqLkukecis sag2Xeyesk1RawxJpolifem seq3Yitedk8MubhVjavaniz deuwohZomvYtipitev xig6Piwusq1MuqxFqalipuq


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

Utilitarian small

  • neqi3OpuleMlidoyeq koga3JilvRjezorom IGNA

  • usekeJdoqomot hezvWwubheub Bhemef gvbno

  • iriguYpupuyod rilfRnagqoih Hbakut znzme 55 72

  • erepeBxutojix

Utilitarian large

  • CLKComplicationTemplateUtilitarianLargeFlat: Displays an image followed by a long text string on a single line.
    imageProvider textProvider SF ZOO 10:09 PM 3 MIN


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

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.

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.
Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.
© 2024 Kodeco Inc.

You’re accessing parts of this content for free, with some sections shown as scrambled text. Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now