Apple Watch complications and widget, help needed. How to start?

I am completely lost on the HA companion app for iOS both in Apple Watch complications as the widgets (iOS 14). It seems so easy, there is some documentation but I do not know what to enter where.

I use Home Assistant as a dashboard, I have a Homey device which is the center of my home And I use Siri. But I want some things in a widget or complication. As a status or maybe even act upon it.

Is there a tutorial to begin with? Or a better documented guide than HA’s one?

Here is a walk through:
To setup Apple Watch complications, open the Home Assistant iOS companion app and go to “App Configuration” under the menu and then select “Apple Watch”.

Add the complication to Home Assistant:
To add a new complication select “Add”
Pick the type of complication that you want to add. The type of complication will determine which watch faces it will work with.
This page from Apple shows you what the different complication types look like:

Lets walk through an example using “Circular Small” because that is usable in several different watch faces.
And lets assume that you have a sensor in Home Assistant that provides the temperature for your bedroom called “sensor.bedroom_temperature”.

Ok, so at this point you should have picked “Add” and then picked “Circular Small”.

Set the name of your complication:
First set the “Display Name” so that you can recognize it on your Apple Watch. For this, lets change the Display Name to “Bedroom temp”. (You don’t need to put a name here, it’s just makes it easier for you to know which complications are which).

Fill out what you want the complication to display:
Ok for the “Template” we want to show a temperature (number) with a ring around it. So select “Template” and change it to “Ring Text”

Now, in the “Inside Ring” text box enter the template that will return the value of your temperature sensor. For this example it will be:
{{ states("sensor.bedroom_temperature") }}

Now press “Preview Output” and it should show you the current value of your bedroom temperature sensor. If it doesn’t, then you didn’t do something correct in the template.
You should be able to use the same templates here that you would use other places in Home Assistant.

Ok, now click “Color” and then pick the color you want the text to be.

Now we want to set how much of the outside sensor is filled.
In the text box below “Ring” you need to enter a template that will return a value between 0 and 1 which will control how much of the ring is filled.

Assuming your temperature is in Fahrenheit, lets use the value that we get from dividing the temperature by 100. So to do that use the following template:
{{ states("sensor.bedroom_temperature")|float / 100.0 }}

That gets the sensor value, turns it into a floating point number and then divides it by 100.

Again, select “Preview Output” and you should see a number between 0.0 and 1.0 that corresponds to your temperature.
Now select the color for the ring.
And now Save your complication by hitting “Save” in the top right corner.

Sync the complication to your watch:
Your complication is now (almost) ready to use on your Apple Watch. Before it can be used, the Apple Watch iOS app needs to sync with the Apple Watch.
One way you can force it sync is as follows:

1. In the Home Assistant Companion app, navigate to App Configuration -> Apple Watch and stay on that screen (you should already be here after saving)
2. Now launch the "Home Assistant" Apple Watch app on your watch.
3. Press the Back button inside Home Assistant Companion mobile app, bringing you back to the main settings screen.
4. Press "Done" in the top right to sync and update the complications on your Apple Watch.

Now the complication should be ready to use in your Apple Watch.

Add the complication to a watch face:
Pick a watch face that supports the Circular Small complication like “Color”
Edit the complications and for “Top Left”, scroll down to Home Assistant and select “Bedroom temp”

Boom! You have the temperature from Home Assistant on your watch. Yay!


Question. I managed to put all my lights on my watch. Is there a way to change the color of an icon based on the status of the switch? So I can see which lights are on and which are off.
Thank you

I don’t believe that is supported, but it would be a great feature.

1 Like

First, thank you Richard! I’d been struggling with this as well and your instructions are great! I was able to create a complication for a bedroom temp sensor and preview both the temp value and the ring “range” value successfully. I am not able to see it in the Watch app no matter what watch face I select. Thinking the sync steps might be hit or miss I let things simmer overnight and still no luck this morning. Anyone have any ideas?



Which face type and complication type are you trying to use together? For example, if you create the complication like in the tutorial (circular) it won’t work with the modular face. It won’t even show up in the list. You need to create the right kind of complication.

The manual sync is only to expedite the process but your phone will sync complications every 30 min according to Apple’s docs — and I’ve found that to be accurate.

I followed exactly the same steps, but the complication i created is never showed up.

There’s a bug in 2021.1 (and earlier) which will not correctly update the watch when you do not have any complications that contain templates. If you’re experiencing this, you can either install the beta or create a complication that you do not intend to use that contains something like {{now()}}.

If you are not in this category of issues, it’s either: not creating a complication of the correct type (this should be improved - it’s really hard to understand which to create) or it’s not syncing the updates to the watch app. Restarting the watch and launching the watch app can sometimes force this to happen easier.

The underlying cause of this being annoying is largely that the app and the watch are talking to each other. Believe it or not, it would actually be more reliable for the watch to talk to your HA instance for complication configuration than talking to the watch. This, however, is a big chunk of work; I’m hopeful that these last few syncing issues can be improved as best we can at least.

1 Like

@zacwest Does this apply to all versions 2021.1? I have the 2021.1.5 and wanted to know. Thanks

The version I am referring to in the previous message is the iOS app. The release that started rolling out yesterday – 2021.2 – has the fix for the aforementioned issue. You can manually upgrade to it in the App Store, or wait for the slow rollout to reach you with automatic updates.

1 Like

@zacwest thank you so much for you prompt answer, it is working now but I stil have some “issues” since the complications only appear is some watch faces. I’ve tried the example of @_Richard and works on the Color watch face but only on that one… then I created a “Modular Large” that doesn’t work in any watch faces that in theory support that type and finally I’ve test with a a “Modular Small” which only works on the “Modular” face only. This is a bit odd but I still need to do some more tests since I wanted to have a Watch Face only with HA complications but it seems not so easy :slight_smile: The other thing that I noticed is that the update on the complications data is not vey regular. Any suggestion is more than welcome. Thanks!

There are two complications which are not working correctly in 2021.2 as well, and are fixed for 2021.3. These are:

  • Graphic Bezel Circular Text – when not setting the text
  • Graphic Rectangular Standard Body – when not setting the line 2 text

You can upgrade to the beta to get on the beta version with the fix if this is what is impacting you.

These only fix cases where entering less than every text field is broken. In most complications, all possible text fields are required; the UI currently does not do a good job of pointing this out. I suggest making sure you’re doing that.

Complications update at :00, :15, :30, and :45 of the hour, within about 5 minutes of those times. This is an Apple restriction, and I have not seen this fail to occur in testing. If you are seeing issues with it updating, I suggest providing more information so we can try and debug it. It has similar connectivity requirements as the phone, but since the watch cannot itself determine if your phone is on Wi-Fi or not, it can be slightly flakier depending on your location permission.

1 Like

Modular Large is only supported on the Modular watch face, and it seems to work with Home Assistant for me.

If you want to know what Complications work with which watch faces I have created a table/page that contains that information (at least, as best as I can determine):

If you are looking for complication types that work on the largest number of watch faces, try Utilitarian Large, and Graphic Corner.

The update speed on complication data is the main downside of Home Assistant Apple Watch complications to me. For sensor data that you want to see the very latest it’s not very useful. So I still use PushOver Glances to get instantly updated complications (updated by push notifications). But Pushover is much more limited on its complication types.


@zacwest your explanation over the updates schedule match what I was sawing and don’t see an issue that needs further troubleshooting. Anyway thanks again for the prompt answer.
@_Richard I’ve made some progress and test additional complications and have the “ circular graphic” working together with the “Graphic Rectangular” on the “Infograph Modular” face :+1:.
I was thinking to create somehow a similar table but I will check the one shared. Again thanks to both!

Really helpful walk through!

I am stuck with just having “Placeholder” as my option under the Home Assistant complication list, despite having created a couple complications (that seem to work in Preview) and followed the force sync instructions several times. I have also reinstalled the app.

Any ideas?


I’m a little late to respond, but did you figure out how to change the color of an icon based on the status?

After reading this guide:

and experimenting making a bunch of different examples and testing with infograph and every corner I got my data to show up in some of the corners but just placeholder in others.

1 Like

Thanks to this forum I managed to get some home assistant sensors and actions on my Apple watch.
Including: Netatmo outdoor temp (C), energy costs ($AUD), rain sensor (mm), solar gen (kWh), Wind (km).

I can’t seem to work out the Gauge code.
The example given is

{{ range(1, 100) | random / 100.0 }}

What code do I need to make the gauge range for the solar, from 0-80 (kWh) for example?


1 Like

Cheers @zacwest