The widget editor

The widget editor is where you make widgets of your own, on any plan. How a widget works explains what a widget is made of, and the tutorial Make your own widget builds one from start to finish. This page is a tour of the editor itself.

Ways in

The Workshop in the sidebar lists your widgets and partials (with your themes and models), each with Edit, and has New › Widget and Partial.
Make a widget… at the bottom of the widget picker, while you add a tile.
Make this widget yours… in a tile’s menu in edit mode copies what that tile draws. The first time you save, your widget is put on that tile.
Make a copy on a widget’s page in the community.

New widget asks how to start:

Start from a widget copies a built-in or one of yours, with its device and settings. It is the easiest way to learn, since it already works.
Start empty has no device of its own: you add what it needs as settings, for anything at all.

Give it a name and choose Start editing. Nothing is saved until you save.

Template, Style and Settings

The three tabs hold the widget: the Template (HTML with Liquid), the Style (CSS) and the Settings each tile can choose. In the template, typing {{ adds the closing }}, with the cursor in between. Settings can be edited as a Form or as JSON, and A tile’s settings shows what a tile will ask for. Each device setting says which of your devices it fits.

The strip beside the code opens panels that slide over it, or stay beside it when you pin them:

Data: what the template can read, with the preview’s values. + inserts one at the cursor.
Actions: what a tap can do. Insert puts it at the cursor.
Catalog: the components and partials a template can use.
Syntax: expressions and their functions.
Test devices, Details and History, below, and Build with your AI: see Build widgets with your AI.

Under the code, the editor checks your widget as you type against every demo: No problems with any demo, or each error and warning with its line.

Settings that hold tiles

A Tiles setting lets a tile of your widget hold other tiles, which its owner chooses and places: a room card with its lights, a row of scene buttons. Add one from the kind picker on the Settings tab, and set:

Layout: a Grid keeps the places the tiles were put in; a List reads them in order.
Pages: lets its owner make pages, each with a name, an icon and a When to show.
What can be added: devices, flows, moods, and widgets that need none. At least one stays ticked.
Most tiles: up to 128 in one widget.

A widget can have several Tiles settings. Each has its own Arrange… window on the tile, named after the setting. Your template draws the tiles: Tiles your users place shows how. The preview makes up some tiles, and pages when the setting has them, since no dashboard has any yet.

What happens to your users’ tiles. Tiles live in a Tiles setting by its name, so changing the settings of a widget that is already on dashboards affects them:

Renaming a Tiles setting keeps them, when it is the only one that changed. One setting goes and one new one comes, and the tiles move to the new one.
Removing a Tiles setting, or renaming it while others change too, takes the tiles inside it away. Saving asks first: Save …? This save leaves out a Tiles setting. The 6 tiles inside it go. Say no and nothing is saved.
Going back to an earlier save, turning Use mine instead of the built-in on or off, and Delete… ask the same way. A widget you publish to the community can’t remove a Tiles setting in an update of the same major version, and an update that does is never installed by itself.

Changing the Layout, What can be added or Most tiles doesn’t remove tiles already placed.

The preview

The preview draws your widget at its true size from the code as you type.

Preview with picks the device for each place: one of your Homey’s, a test device, or the demo. A setting that may stay empty starts Left empty, as on a new tile.
State shows the device in each state it can be in, such as on, off and unavailable. With your own device it is Now or Unavailable.
The screen (Desktop, Tablet, Wall panel, Phone) and the tile size (Smallest, Default, Wide, Tall, Large, and Icon, Bar and Pill for a widget that goes that small) show it the way a dashboard would.
Taps on the preview are listed instead of sent. Send taps to my Homey sends them for real.

Test devices

A test device is a device you make up for the preview: it never reaches your Homey or a dashboard, and every widget of yours can use it. Use one to see a state your own devices are rarely in, such as a low battery or a sensor that’s offline.

New test device in the Test devices panel makes one; Make a test device on a device setting makes one that fits and shows it at once. Change its values, or switch Available off, and the preview follows.

Save and go back

Save (or ⌘S, Ctrl+S on Windows and Linux) makes your widget live on every tile that uses it. You can say what changed, and while there is an error, Save says how many to fix first. The footer says where it is used: “Saved 2 minutes ago · on 3 tiles on Home”. Until you save, tiles keep drawing your last save, and Discard changes goes back to it.

History lists your saves. Tiledash keeps the last 100 of a widget, and every one while it is in the community; partials keep 10. Compare shows what changed, and Go back puts an earlier save in the editor. Your tiles show it once you save it.

Details

In the widget picker: the line under its name when you add a tile.
Size of a new tile, for a widget started empty.
Use mine instead of the built-in …, for a widget started from a built-in: every tile of that built-in draws yours, on every dashboard, until you switch it off. Save once first.
Delete…: tiles that used it go back to the widget it was based on.

A widget copied from a built-in or from the community says where it came from. When that one gets a newer version, the editor offers to bring the changes into your copy: See what changed, then Bring the changes in.

Publish to the community… next to Save shares your widget in the community: see Publish your widget to the community.