# Home Assistant iOS Widgets for iPhone and Apple Watch • Aivi Docs

> Home Assistant widgets on your iPhone Home Screen, Lock Screen, StandBy, and Apple Watch, set up from a panel in Home Assistant, with pressable tiles. Needs iOS 26.

Source: https://docs.getaivi.app/guides/homeassistant-widgets/

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](https://docs.getaivi.app/home-assistant/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](https://getaivi.app/#pricing), and the first week is free.

[Set it up in a few minutes](#set-up-home-assistant-widgets-on-ios) · [Pick a template for your sensor](#which-template-for-which-sensor) · [Control devices](#control-devices-from-a-widget) · [Compare with the Companion app](#aivi-or-the-companion-apps-widgets)

## 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.**

[Recommended HACS integration Choose your entities in a form in Home Assistant and watch the widget take shape in a live preview. Buttons and switches work as they are, with no Home Assistant Cloud. Set it up](#with-the-hacs-integration-recommended)

[Blueprints Plain automations you import and adjust, with an option for every detail. ](#with-a-blueprint)[Your own automations Full control. You write the YAML; buttons need a public webhook.](#write-your-own-automation)

### With the HACS integration (recommended)

1. Install [Aivi from the App Store](https://apps.apple.com/app/aivi/id6749237387), 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](https://docs.getaivi.app/home-assistant/integration/#install) 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](https://docs.getaivi.app/home-assistant/integration/) covers the rest: Live Activities, buttons on your Home Screen, and what to do when something does not update.

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

1. Install [Aivi from the App Store](https://apps.apple.com/app/aivi/id6749237387), 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](https://www.home-assistant.io/integrations/rest_command/) to your `configuration.yaml`, then reload your 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 }}'
   ```

   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:

   [![Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint pre-filled.](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fha.getaivi.app%2Fblueprints%2Fwidget-gauge-v1.yaml)

   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](https://docs.getaivi.app/home-assistant/blueprints/#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.

Prefer to write the automation yourself? [Write your own automation](#write-your-own-automation) has a complete example.

## Which template for which sensor

| What you want to show                | Template                                                                       | Typical Home Assistant source                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| One reading on a dial                | [Gauge](https://docs.getaivi.app/widget-templates/#gauge-template)             | Temperature, humidity, CO₂, air quality                                         |
| A headline value with a state line   | [Status](https://docs.getaivi.app/widget-templates/#status-template)           | Thermostat, alarm, washer state                                                 |
| Several device batteries at once     | [Battery](https://docs.getaivi.app/widget-templates/#battery-template)         | Phones, locks, sensors, cameras                                                 |
| Solar, grid, battery, and home       | [Energy](https://docs.getaivi.app/widget-templates/#energy-template)           | Power (W) sensors from your inverter, meter, or battery                         |
| Electricity prices through the day   | [Prices](https://docs.getaivi.app/widget-templates/#prices-template)           | Nord Pool (example in the blueprint), or any hourly price list via a template   |
| A value and where it’s heading       | [Trend](https://docs.getaivi.app/widget-templates/#trend-template)             | Indoor temperature, power use                                                   |
| Time until something                 | [Countdown](https://docs.getaivi.app/widget-templates/#countdown-template)     | Any timestamp sensor: next alarm, waste pickup, calendar event                  |
| A few labeled values                 | [List](https://docs.getaivi.app/widget-templates/#list-template)               | Door and window states, room temperatures (up to eight rows)                    |
| Spending against a limit             | [Budget](https://docs.getaivi.app/widget-templates/#budget-template)           | Monthly energy cost                                                             |
| Progress toward a finish             | [Progress](https://docs.getaivi.app/widget-templates/#progress-template)       | Dishwasher, backup, charging                                                    |
| A device with a picture and readings | [Showcase](https://docs.getaivi.app/widget-templates/#showcase-template)       | Car, vacuum, 3D printer, plant sensor                                           |
| Buttons and toggles                  | [Switchboard](https://docs.getaivi.app/widget-templates/#switchboard-template) | Scenes, scripts, lights, switches (see [below](#control-devices-from-a-widget)) |
| One device and its controls          | [Remote](https://docs.getaivi.app/widget-templates/#remote-template)           | 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](https://github.com/SukramJ/homematicip_local) integration (for a CCU3 or OpenCCU) or the built-in [Homematic IP Cloud](https://www.home-assistant.io/integrations/homematicip_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](https://docs.getaivi.app/widget-templates/#switchboard-template) 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](https://docs.getaivi.app/widget-templates/#remote-template) widget has buttons and toggles the same way.

With the [HACS integration](https://docs.getaivi.app/home-assistant/integration/#buttons-and-switches-on-your-home-screen), 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](https://docs.getaivi.app/home-assistant/switchboard-automation/) 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

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](https://companion.home-assistant.io/docs/integrations/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](#control-devices-from-a-widget) 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?

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](https://docs.getaivi.app/guides/homeassistant/) 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](https://docs.getaivi.app/concepts/how-it-works/#marking-content-as-stale).

## 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](https://docs.getaivi.app/home-assistant/integration/#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](https://docs.getaivi.app/limitations/#widgets) 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 entities change, so your phone never needs to reach your Home Assistant.

**Can I control devices from an Aivi widget?** Yes, with the [Switchboard](#control-devices-from-a-widget): 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

For anything the integration and the blueprints don’t cover, call the widget endpoint from your own automation, with the same [RESTful command](https://www.home-assistant.io/integrations/rest_command/) pattern as [Live Activities](https://docs.getaivi.app/guides/homeassistant/). If you set up a blueprint, you already have it; otherwise add it to `configuration.yaml`:

```yaml
rest_command:
  update_widget:
    url: "https://api.getaivi.app/widgets/{{ slug }}"
    method: PATCH
    headers:
      content-type: application/json
      authorization: Token [token]
    payload: "{{ payload }}"
```

Make sure to replace `[token]` with your API token from the Aivi app.

Then call it from an automation whenever the source data changes. This example keeps a [Gauge](https://docs.getaivi.app/widget-templates/#gauge-template) widget in sync with a temperature sensor:

```yaml
- 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](https://docs.getaivi.app/widget-templates/#choosing-a-template) 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.
