Skip to content
Get the appGet app

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

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.

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

  2. In the Widgets tab, create a widget: pick a template (Gauge is a good first one) and add it to your Home Screen.

  3. In Home Assistant, install the Aivi integration through HACS and paste your token. The integration guide has the two buttons that do it.

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

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.

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

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

  3. Add a RESTful command to your configuration.yaml, then reload your configuration:

    rest_command:
    update_widget:
    url: 'https://api.getaivi.app/widgets/{{ slug }}'
    method: PATCH
    headers:
    content-type: application/json
    authorization: Token [token]
    payload: '{{ payload }}'
  4. 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.

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

What you want to showTemplateTypical Home Assistant source
One reading on a dialGaugeTemperature, humidity, CO₂, air quality
A headline value with a state lineStatusThermostat, alarm, washer state
Several device batteries at onceBatteryPhones, locks, sensors, cameras
Solar, grid, battery, and homeEnergyPower (W) sensors from your inverter, meter, or battery
Electricity prices through the dayPricesNord Pool (example in the blueprint), or any hourly price list via a template
A value and where it’s headingTrendIndoor temperature, power use
Time until somethingCountdownAny timestamp sensor: next alarm, waste pickup, calendar event
A few labeled valuesListDoor and window states, room temperatures (up to eight rows)
Spending against a limitBudgetMonthly energy cost
Progress toward a finishProgressDishwasher, backup, charging
A device with a picture and readingsShowcaseCar, vacuum, 3D printer, plant sensor
Buttons and togglesSwitchboardScenes, scripts, lights, switches (see below)
One device and its controlsRemoteCar 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.

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.

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.

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.

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.

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 in configuration.yaml is 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.

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.

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.