Home Assistant iOS Widgets for iPhone and Apple Watch
The Home Assistant Companion app has iOS widgets for controls and simple sensor displays, refreshed on a timer. Aivi adds thirteen widget templates: display templates, such as energy flow, gauges, device batteries, and electricity prices, plus a Switchboard and a Remote with buttons you can press. The free Aivi integration sets up every one of them from a panel in Home Assistant, with a live preview. Widgets need iOS 26. Aivi costs $2.99 a month or $23.99 a year, and the first week is free.
Set it up in a few minutes · Pick a template for your sensor · Control devices · Compare with the Companion app
Set up Home Assistant widgets on iOS
Section titled “Set up Home Assistant widgets on iOS”You need an iPhone on iOS 26 or later, and a Home Assistant that can make outgoing HTTPS requests. Any installation type works: no port forwarding, no Home Assistant Cloud, and no remote access to your Home Assistant.
There are three ways to do it. We recommend the HACS integration.
With the HACS integration (recommended)
Section titled “With the HACS integration (recommended)”-
Install Aivi from the App Store, open the Settings tab, sign in, and start your free week. Then copy your API token from the same tab.
-
In the Widgets tab, create a widget: pick a template (Gauge is a good first one) and add it to your Home Screen.
-
In Home Assistant, install the Aivi integration through HACS and paste your token. The integration guide has the two buttons that do it.
-
Open Aivi in the Home Assistant sidebar, select your widget, and choose the entities that feed it. The preview shows the widget as you go. Select Save.
The integration guide covers the rest: Live Activities, buttons on your Home Screen, and what to do when something does not update.
With a blueprint
Section titled “With a blueprint”Prefer plain automations? A blueprint gives you one automation per widget
that you can read and edit, with an option for every detail. It needs one
rest_command in your configuration.
-
Install Aivi from the App Store, open the Settings tab, sign in, and start your free week. Then copy your API token from the same tab.
-
In the Widgets tab, create a widget: pick a template (Gauge is a good first one) and give it a slug such as
living-room. Your automation updates the widget by this slug. -
Add a RESTful command to your
configuration.yaml, then reload your configuration:rest_command:update_widget:url: 'https://api.getaivi.app/widgets/{{ slug }}'method: PATCHheaders:content-type: application/jsonauthorization: Token [token]payload: '{{ payload }}' -
Import the blueprint for your template, and point it at your sensor and the slug from step 2. This one is for the Gauge:
The blueprint updates the widget whenever the sensor changes. To send the first update right away, open the new automation, tap ⋮, and choose Run actions. Every display template has a blueprint; see the widget blueprints.
-
Put the widget on screen:
- Home Screen: long-press an empty area, tap Edit, then Add Widget, and choose Aivi and a size.
- Lock Screen: long-press the Lock Screen, tap Customize, choose the Lock Screen, tap the widget area, and choose Aivi.
Then long-press the placed widget, tap Edit Widget, and pick yours under Widget. iOS usually shows the content within a few minutes.
Which template for which sensor
Section titled “Which template for which sensor”| What you want to show | Template | Typical Home Assistant source |
|---|---|---|
| One reading on a dial | Gauge | Temperature, humidity, CO₂, air quality |
| A headline value with a state line | Status | Thermostat, alarm, washer state |
| Several device batteries at once | Battery | Phones, locks, sensors, cameras |
| Solar, grid, battery, and home | Energy | Power (W) sensors from your inverter, meter, or battery |
| Electricity prices through the day | Prices | Nord Pool (example in the blueprint), or any hourly price list via a template |
| A value and where it’s heading | Trend | Indoor temperature, power use |
| Time until something | Countdown | Any timestamp sensor: next alarm, waste pickup, calendar event |
| A few labeled values | List | Door and window states, room temperatures (up to eight rows) |
| Spending against a limit | Budget | Monthly energy cost |
| Progress toward a finish | Progress | Dishwasher, backup, charging |
| A device with a picture and readings | Showcase | Car, vacuum, 3D printer, plant sensor |
| Buttons and toggles | Switchboard | Scenes, scripts, lights, switches (see below) |
| One device and its controls | Remote | Car lock and climate, garage door, vacuum |
The Countdown, Prices, and Progress templates keep themselves current on the device between updates, so a countdown keeps ticking and the current price hour moves on without Home Assistant sending anything.
Homematic IP devices work like any other entity once they are in Home Assistant, through the Homematic(IP) Local integration (for a CCU3 or OpenCCU) or the built-in Homematic IP Cloud one: a thermostat or weather station feeds the Gauge or Status template, and window contacts fit the List template.
Control devices from a widget
Section titled “Control devices from a widget”The Switchboard template is a grid of up to eight pressable tiles on the Home Screen: buttons for scenes and scripts, and toggles for lights, switches, locks, garage doors, and fans. Everyone you share the widget with can press it too. The Remote widget has buttons and toggles the same way.
With the HACS integration, you choose the entities that become tiles in the Aivi panel. A press reaches Home Assistant over a connection it opens itself, with no webhook, no open port and no Home Assistant Cloud, and the tile shows the new state once Home Assistant has carried it out.
To build it with your own automations instead, Switchboard without the integration has the complete example: presses arrive through a webhook, so Home Assistant has to be reachable over public HTTPS on port 443, for example with a Home Assistant Cloud webhook URL. There is no blueprint for the Switchboard or the Remote.
On Apple Watch
Section titled “On Apple Watch”Every template also renders as corner, circular, rectangular, and inline complications, and Aivi widgets join the watch’s Smart Stack. Add one like any other complication: touch and hold the watch face, tap Edit, choose a complication slot, and pick Aivi.
Aivi or the Companion app’s widgets?
Section titled “Aivi or the Companion app’s widgets?”The Companion app’s iOS widgets cover controls (scripts, dashboard shortcuts, tiles that toggle entities, Assist) and sensor displays, including gauges and template lines. They refresh about every 15 minutes within an iOS budget. If you mostly want buttons for your home, they are free and a good fit: their controls go through the Companion app’s own connection to Home Assistant, with no webhook to set up.
Aivi is the better fit if you want:
- Templates designed for your data. Eleven display layouts, from Energy to Prices, each built for its kind of data at every size, with any SF Symbol as the icon. With the Switchboard and the Remote, that makes thirteen widget templates.
- Pushed, not polled. Home Assistant sends new content when a sensor changes, and it usually shows up within minutes. Countdowns, price timelines, and progress with an end time keep moving on the device between updates.
- Sharing without Home Assistant accounts. Up to five people see the same widget on their own devices (iOS 26 or later); they install Aivi and pay nothing.
- Controls that show the confirmed state. A Switchboard tile only looks on when Home Assistant says so, and people you share it with can press it without a Home Assistant account. With the integration, presses need no webhook and no remote access.
- Several widgets in one place. The Aivi Board combines your widgets as tiles in a single widget.
How fresh are the widgets?
Section titled “How fresh are the widgets?”iOS treats widgets as a background, battery-friendly surface, for every app. When Home Assistant updates an Aivi widget, the change typically appears within minutes: often faster, occasionally slower in Low Power Mode or on a sleeping device. Design for “latest known state”, not for second-by-second updates.
- For something happening right now, like a wash cycle or a charging session, use a Live Activity instead: that is the real-time layer.
- To see how old a value is, set a staleness threshold on the widget. Once its content is older than that, it shows “as of 14:32” instead of passing old data off as current. See marking content as stale.
Widgets not working or not updating?
Section titled “Widgets not working or not updating?”With the integration, problems appear under Settings → System → Repairs,
each with what to do; see If something is not
working. The checks
below are for blueprints and your own automations. When an update fails, Home
Assistant logs a rest_command warning with the status code under
Settings > System > Logs:
400: the slug belongs to a widget with a different template.401: the token inconfiguration.yamlis missing or mistyped. Copy it again from the app and reload your configuration.402: the token is valid, but the account has no active subscription.404: no widget with that slug exists. Create it in the Widgets tab first, and check that the slug matches exactly.422: the content doesn’t fit the template or is over 4 KiB, usually from a hand-written payload.
The widget stays empty. Long-press the widget, tap Edit Widget, and check that it points at the right Aivi widget. With a blueprint or your own automation, also open the automation and use Run actions to send the first update.
Updates are slow. Check Low Power Mode, and trigger on meaningful changes rather than every sensor tick. See Limitations for how iOS budgets widget updates.
Common questions
Section titled “Common questions”My Companion widgets are empty or stale. Will Aivi fix them? Aivi is a separate setup, not a repair for the Companion app’s widgets. Its widgets get their content pushed when your entities change, so your phone never needs to reach your Home Assistant.
Can I control devices from an Aivi widget? Yes, with the Switchboard: its tiles run scenes and scripts or toggle entities from the Home Screen. With the integration, presses reach Home Assistant over a connection it opens itself, with no webhook and no remote access; with your own automations they arrive through a public HTTPS webhook. The other templates show state, and tapping one opens a link you choose, such as a Home Assistant dashboard. Aivi and the Companion app’s widgets can sit side by side.
Do I need the Companion app? Not for Aivi. Home Assistant talks to Aivi’s API directly, and the Aivi app shows the widgets.
How many widgets can I have? Up to 20, plus up to five Live Activities running at once.
How much does it cost? $2.99 a month or $23.99 a year, with the first week free. People you share with pay nothing.
Write your own automation
Section titled “Write your own automation”For anything the integration and the blueprints don’t cover, call the
widget endpoint from your own automation, with the same
RESTful command
pattern as Live Activities. If you set up a
blueprint, you already have it; otherwise add it to configuration.yaml:
rest_command: update_widget: url: "https://api.getaivi.app/widgets/{{ slug }}" method: PATCH headers: content-type: application/json authorization: Token [token] payload: "{{ payload }}"Then call it from an automation whenever the source data changes. This example keeps a Gauge widget in sync with a temperature sensor:
- triggers: - trigger: state entity_id: sensor.living_room_temperature actions: - action: rest_command.update_widget data: slug: living-room payload: >- { "content": { "template": "gauge", "value": {{ states('sensor.living_room_temperature') | float(0) }}, "min_value": 10, "max_value": 35, "unit": "°C", "label": "Living room", "icon": "thermometer.medium" } }The content must match the widget’s template; the
widget templates list every
field.
There is no need to update on a timer: widgets show the latest known state, so updating only when the value actually changes is enough. For slow-moving data (battery levels, prices), a time-pattern trigger every hour or a single nightly update works just as well.
Aivi: Live Activities and widgets over an API · Pricing · App Store