Researched from current Home Assistant, Companion app and Apple documentation on October 20, 2026. This is an illustrative configuration walkthrough, not a test on physical phones or smart-home hardware. Menus vary by app and operating-system version. The cover is an AI-generated editorial illustration.
Start with one button and one reading
Home Assistant phone widgets are useful for a small everyday job: start reading-time lighting, or glance at the living-room temperature. Begin with the official Companion app already signed into your Home Assistant server. Keep the first button separate from the temperature display so you know whether a tap should change something or only show information.
Our suggested first layout is two clearly named items: Reading light on and Living-room temperature. An explicit “on” command avoids a second tap turning the lamp back off. Before connecting that button to a real light, build the practice routine below. It gives both phones the same harmless result to check.
An entity is one named control or reading, such as a lamp or temperature sensor. A script is a saved set of actions. Keeping the behavior in a script lets a phone button and dashboard button call the same routine; see when to use scenes and scripts for a larger lighting preset.
1. Create a harmless practice routine
- Open the Companion app and confirm it reaches your usual dashboard on home Wi-Fi. Update the app through its normal app store if needed; updating the server does not update the phone app.
- Using an administrator account, go to Settings → Devices & services → Helpers → Create helper → Toggle. Name it Widget practice. This is a software switch with no hardware attached. Keep it out of existing automations.
- Check its entity ID. The example uses
input_boolean.widget_practice; substitute your actual ID if different. Leave the helper off and keep its control open in a second browser window. - Go to Settings → Automations & scenes → Scripts, create a new script, and choose Edit in YAML from its menu. Replace the new script’s contents with this block, then save.
alias: Widget practice on
mode: single
sequence:
- action: input_boolean.turn_on
target:
entity_id: input_boolean.widget_practiceYAML is the indented text format used by the editor. Paste this into one script’s editor, without a surrounding script: heading. Run the saved script once: the helper should become on. Turn the helper off again using its control. The Toggle helper reference documents the software switch; the Scripts reference explains saved sequences.
Record the script’s actual entity ID too; the following steps assume script.widget_practice_on. A script’s own on/off state indicates whether it is running, so use the helper to check this short routine’s lasting result.
2. Add the Android button
- Long-press an empty Home Screen area, open Widgets, find Home Assistant, and place an Action button.
- Select the saved script’s action, Widget practice on (
script.widget_practice_on). This script needs no extra action data. Give the button a clear label and save. - Tap it and inspect the helper in the second window. Android’s green check means the action call succeeded; it does not prove a physical device moved.
For temperature, add an Entity State widget and select your temperature sensor. Choose refresh rather than toggle where the tap option is offered. The Action button also offers Require authentication for a phone credential check. See the Android widget instructions.
3. Add the iPhone button
- Touch and hold an empty Home Screen area, choose Edit → Add Widget, and find Home Assistant. Add its Scripts widget, then edit it to select Widget practice on.
- Tap the script and inspect the helper in the second window. If your installed app offers a different widget picker, check its available types against the current reference below.
- Add a Sensors widget for your temperature sensor. Its documented refresh interval is approximately 15 minutes, not a guaranteed live feed.
If using Custom Widget (BETA), create it under Companion App Settings → Widgets → Create, explicitly choose Run script, then select that custom configuration in the Home Screen widget. Enable Show last update time to make display age visible. See Home Assistant’s iOS widget options and Apple’s add/edit instructions.
4. Check commands and displays separately
This rehearsal deliberately uses a persistent software value. It avoids guessing from a brief animation or changing real devices. The outcomes below follow the example’s logic; they are expected results, not measured phone performance.
On a narrow screen, scroll the table sideways.
| Try this | Expected result | What it tells you |
|---|---|---|
| Helper off; tap the practice button once | Helper becomes on in the open Home Assistant window | The button reached the intended script and helper. |
| Helper on; tap again | Helper stays on | This command sets a value; it does not reverse it. |
| Turn helper off in Home Assistant; tap again | Helper returns to on | A fresh command works, rather than merely showing the previous result. |
| Compare a temperature widget with its entity inside the app | The widget may show an older reading | Display freshness needs its own check. The practice button test does not establish it. |
A recent widget refresh time does not prove that the sensor itself supplied a new measurement. If both the widget and the app show an old or unavailable reading, check the sensor’s own update history before changing the widget.
Once this works, create a separate script for the reading lamp and point the phone button at it. In the visual script editor, add Light: Turn on and select only the intended light. Check the lamp from its normal control first, then run the script while watching it. Keep locks, garage doors, alarms and essential lighting out of the first experiment. Home Assistant’s light actions describe the available commands.
Keep an ordinary way to turn the lamp off. A script is a command, not a permanent override of other automations. For lighting that should stay under manual control afterward, use the separate manual-override walkthrough.
5. Fix the failing part
| What you observe | Check next | Keep the test small |
|---|---|---|
| The practice script fails even inside Home Assistant | Check its target helper ID and saved action. | Fix the script before changing phone settings. |
| The app cannot open Home Assistant either | Check the selected server and connection. | Restore app access before rebuilding the widget. |
| The app works, but Android’s widget fails | Turn Data Saver off for the test and allow Home Assistant’s background data. | Then recreate just the practice widget if needed. |
| A tap opens a page without changing the helper | Check whether the widget is set to navigate or run the practice script. | If the correct action still fails, record the app version and reproduce with the helper before reporting it. |
| The helper changes but a displayed reading looks stale | Open the entity in the app and compare values. | Investigate refresh behavior rather than repeatedly sending commands. |
| Home Wi-Fi works; mobile data does not | Check remote access and, if used, the phone’s VPN connection. | Repeat with the practice helper, not a door lock. |
Android’s current documentation describes a default 30-minute refresh while the screen is on; newer releases can need additional notification access for faster updates. Permission labels vary by Android release. Read the refresh prerequisites before changing them. On iPhone, background refresh requests remain subject to the operating system’s budget, as the iOS documentation explains.
A home-network address alone is insufficient when the phone is away. Home Assistant Cloud requires a subscription; a properly configured VPN is another route. A VPN is a private connection back to the home network and must actually be connected when needed. Follow the official remote-access options or our remote access without port forwarding guide. A widget does not supply that connection itself.
A simple widget is not a restricted account
For a trusted family member, showing only a few useful controls makes the phone easier to use. It does not prove that their Home Assistant login can access only those controls. Non-admin status, hidden dashboard tabs and a widget’s confirmation prompt do not establish room-only authorization.
The Home Assistant security policy treats logged-in users as trusted, and its view documentation says hidden tabs remain reachable by direct URL. If someone must be prevented from reaching cameras, locks or other entities, read the guide to limiting user access before providing a login.
Common questions
Do I need a new temperature sensor?
No new sensor is needed if the room reading already exists in Home Assistant. Choose that sensor entity, not an unrelated thermostat target temperature. The practice button needs no sensor at all.
Should I use a widget or a notification?
Use a widget for something you choose to check or start. Use a notification when the system needs to get your attention. If the message should ask a question, our actionable-notification guide adds Yes/No buttons.
When planning local routines and shared household controls, agree on a few plain labels before adding more buttons. “Reading light on” tells another person what a tap will do.