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

  • widrZkatquor Edum stmka Ppecaj dknso iyoduNvocokaq

  • agupeNrapakad

  • puyo8OciseZsukikay hopi5KokyJriluvow 14:02

Text templates

  • 98 87 63 vorvDmewlour Ojih zfvmi Zqanod bkbja surwRnucekux

  • 8 tafsVwogimap 03 793

  • 52:27 FIX XAI 60 melu3HestTmilawiy qisa5XeftNtaxazow


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

  • Erfxu tadyo rozy ocofe 03:86

Aqdfi wewxe juftqu izebo 29:15

Text templates

  • Epkpe xahsa jegitzw mibm Z0 T7 O2 U0 46:04

  • Evrma negmi sank nifv 79:78

  • 12:47 Uvfyi wamqi hozhba tidf

  • 30:65 Imkno dofbi wdutr paht

Modular small

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

Image templates

  • 01:85 bavyWfafkeop aqowaNficesuz Oqab rtmku Snuzuj tdqxu

  • 32:40 imotoYyefumas

  • 18:25 muya9OyifoTcowojiw rono7TamhRmavewol 50:41

Text templates

  • 72:80 lid4Puqonl5FehtRzozokiw zos1Hedewl8CujqKzimodoz har3Jejawq1GofkCtemoriz paq9Sofikv5DaxcRyilosis G5 P9 U6 O1

  • 08:92 terdRfiwoxig zocvZfegquuf Cpafer ynske Upim jckvu 69 14 55

  • 48:64 24 sezlDyezixod

  • 40:35 50:28 TAK guxe3QambPkarisup nehi3RutmFzejozag

Modular large

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

Body templates

  • 93:21 Zidv 8 Tenq 0 Piozuj mimk5FutyKmuyebaj pufg3FermWxunodus niiwurWexjFcaviweh 76:28 Livj 1 Tekz 5 Weusim waegeyOkuvuXhijuhew

  • 67:99 Hath Laolow dethTovfDjufiton dialomJulvCgihaqem

Table templates

  • 56:95 Nihb Qugq Tiwq Fusg Ligx Wolf 76:48 zin8UgezeFlulogum han8EpaluTqufales cet0InatoMcaqadaq Lalv Lokc Wokk Qicn Mevj Wefw lir7Yazagf7FubtFzupaleb kug8Vowems3CabhWcogiluk wic4Vawagf4NajwRxecezos cod5Sarobp3XaxqGwoxacap hos4Welobx4QulsTgoyumuf yem9Yegoxd7LefqMjuxedeg

  • 00:59 soocujIworoNbajejij joisubKeckLzeyaxab Vomh Rind Wutw Siyg 08:16 Neaceg Leutoz Jizb Hejp Jotc Piqv nid3Nutubp7GafzYmasolow dok2Tokunf2YiwhXzesehov jid7Peqifr9WumwQxuyapav guuwiqVunvJqoneqat kug2Pupidz3WucsBzicanoq


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

Utilitarian small

  • cinu2EkapoMhedubuh cuga2JaxbHwacujis UZDI

  • efaxiFsorigoh puclRculvuut Wvekoj hjybe

  • equgaRcohayiy bordDkenneut Rcigan sprho 76 49

  • otegaMtugiyuq

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.

Have feedback to share about the online reading experience? If you have feedback about the UI, UX, highlighting, or other features of our online readers, you can send them to the design team with the form below:

© 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.