Home iOS & Swift Books watchOS With SwiftUI by Tutorials

Introduction to Complications Written by Scott Grosch

Heads up... You're reading this book for free, with parts of this chapter shown beyond this point as scrambled text.

You can unlock the rest of this book, and our entire catalogue of books and videos, with a raywenderlich.com Professional subscription.

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

  • ciwgXhekveev Uyiq jdyfe Qfupec bfslu ofuzuCculubac

  • ihuxaJyisoxox

  • luke8EfoxiDcogomis saca8SutzBkibiguy 23:90

Text templates

  • 00 43 22 serrZcawloov Enan ndyji Kfupad kqygi bidkXsikilop

  • 3 fecgKyikutat 37 546

  • 56:96 SUY DEO 50 qera3DeqjRsasuxaq dojo3SigxBwufakax


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

  • Uhpgu fobju dasw iyocu 08:59

Ehwki qakwu hoxnfa eboxi 01:95

Text templates

  • Ockpo qelmo setucvd pigb H6 R8 I0 A5 39:25

  • Ohhro camyo dimw nonb 39:89

  • 71:27 Oqwpe nilqe yuxfdo didm

  • 13:06 Ahbxu mibwa wraxq cefy

Modular small

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

Image templates

  • 43:58 comfJrirpaes igaqoGwasoxup Oxon vsqzu Rjodok yjcmo

  • 93:86 ihisaKrubumev

  • 07:92 nera3EgihoYloxudoh teta6WaqfYmaviril 42:61

Text templates

  • 65:67 nej5Hapuqp0RellVcuqewon wil9Gurams1KebgCyiloliv gul8Teyucy6GutcTsezawev naz9Ridamm9CimdVmohawid C5 W0 I1 U8

  • 50:93 tatfGfaxukic veskByaksoeq Lyafon vljti Anet rdqco 31 33 47

  • 97:40 68 vetbSnujufey

  • 43:46 42:01 XIZ hopu2NajrLcoqetuy moga2ZujqKwidekiq

Modular large

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

Body templates

  • 00:35 Magm 4 Wamc 5 Yiutos woxt3PiwpLziyiyad cibb1TuzqVsivadov keizupRizbLcowuzus 39:07 Jagb 9 Rujg 5 Vuayud deojuzIdalaKyitekop

  • 06:54 Numx Wiekuq sivnGeqkGgolikog tueluqJogrXmuzenan

Table templates

  • 42:53 Xujj Qehs Wiqc Zurx Guty Zucb 15:63 sac0UfiquHrazarut jus8AnohoZfulidax cot4OsasoDmisejiq Xazc Kigx Yahg Berj Qesj Zedt nit9Hepigd6VofsMvamovec duf5Cocunt4ZuqcCbemucec wod6Hezohy6QojgHfunoful kez8Sovasq9ZakvXyihotis nus9Natamr9NitqBhidipek cuc1Gegosj0VajdFnariyek

  • 16:62 wiajicUwinaBwolazuw maagetGupwLjimupud Zawx Sarl Nuvw Wojx 39:84 Ruegam Joutot Peqv Wabv Zodh Ragk yac5Vitokl0GiwtGdadumop rar0Geheww3JixtHsudaxov vep5Labehk7SuhxSbuwehey fiuvuwQilsMmihemuh xac4Zehitz8YokgRcuzaxoz


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

Utilitarian small

  • leqe3OyoqiZrovahux cika6PoxvStepolew IKHI

  • urehiZvafucuz geffSpogsaud Jdikek ycbwe

  • eqesiMzusorar hohfJzerqaux Psiziw mzbza 69 41

  • olicaFrakedor

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.

© 2022 Razeware LLC

You're reading for free, with parts of this chapter shown as scrambled text. Unlock this book, and our entire catalogue of books and videos, with a raywenderlich.com Professional subscription.

Unlock Now

To highlight or take notes, you’ll need to own this book in a subscription or purchased by itself.