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 eleven widget templates: ten display templates that your automations fill in, such as energy flow, gauges, device batteries, and electricity prices, each with a one-click blueprint, plus a Switchboard of tiles you can press. 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

You need an iPhone on iOS 26 or later, and a Home Assistant that can make outgoing HTTPS requests. Any installation type works: no custom components, no port forwarding, and no remote access to your Home Assistant.

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/widget/{{ slug }}'
       method: PATCH
       headers:
         content-type: application/json
         authorization: Token [token]
       payload: '{{ payload }}'

   Note

   Replace [token] with your API token from the Aivi app.

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.

Note

Prefer to write the automation yourself? Publishing from Home Assistant has a complete example.

Which template for which sensor

Energy Solar, grid, battery, and home from your power sensors. Gauge One reading on a dial: temperature, humidity, CO₂. Battery Battery levels across your devices. Prices Today's electricity prices, with the current hour marked.

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
Buttons and toggles	Switchboard	Scenes, scripts, lights, switches (see below)

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

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, and fans. A press reaches Home Assistant through a webhook, an automation carries it out, and the tile fills in once Home Assistant publishes the new state. Everyone you share the widget with can press it too. Interactive Widgets has the complete Home Assistant example; there is no blueprint for this one.

Note

Presses need Home Assistant reachable over public HTTPS on port 443, because Aivi delivers them to a webhook. The simplest way is a Home Assistant Cloud webhook URL, which opens no port on your router. The display templates need none of this.

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?

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. Ten 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 below, that makes eleven widget templates.
• Pushed, not polled. Your automation 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. It needs a public HTTPS webhook, such as Home Assistant Cloud’s.
• Several widgets in one place. The Aivi Board combines your widgets as tiles in a single widget.

How fresh are the widgets?

iOS treats widgets as a background, battery-friendly surface, for every app. When your automation 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?

These checks cover Aivi widgets. 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. If you haven’t yet, open the automation and use Run actions to send the first update. Then long-press the widget, tap Edit Widget, and check that it points at the right Aivi widget.

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

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 automation runs, 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. Presses reach Home Assistant through a webhook, so it has to be reachable over public HTTPS, for example with Home Assistant Cloud. The other templates show state, and tapping one opens a link you choose, such as a Home Assistant dashboard. The Companion app’s widgets control entities without a webhook, and both 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.