Settings
A widget declares what each tile can choose in its settings list.
This page lists every kind with what it takes, and what the template reads.
Settings explains how to use them.
Common fields
Every setting has these fields, whatever its kind:
| Field | Type | Default | Rules |
|---|---|---|---|
type | text | none | The kind, from the lists below. Required. |
name | text | none | The key the template reads. Required. Starts with a lower-case letter, then up to 31 letters or digits: ^[a-z][a-zA-Z0-9]{0,31}$. |
label | text | none | What the tile’s dialog calls it. Required. 1 to 60 characters, without spaces at the ends. |
help | text | none | A line under it. At most 200 characters. |
required | yes/no | true | Whether a tile has to choose something. |
group | text | content | The tab of the tile’s settings it sits on: content, layout, look, chart, map or tap. A tap setting starts on tap and a layout setting on layout. |
Rules for the whole list:
- A widget can declare at most 32 settings.
- Every setting needs a name of its own. Two settings can’t share one.
- A setting that points at another one (
of,keepDone) has to point at one that exists and is of the right kind: a device setting, a values setting or a choice setting.
The template reads a setting as settings.<name>.
A simple setting is also a CSS variable, --setting- followed by its name in lower-case words joined with dashes.
Kinds that pick from the Homey
In the editor these are listed as A device, A capability, A flow, A mood and A dashboard. A device, flow, mood or dashboard setting can also hold several: see Several at once.
device
A device of the tile’s Homey.
| Option | Type | Default | Rules |
|---|---|---|---|
requires | object | none | Readings a device must have. all lists readings it needs every one of, any lists readings of which at least one is needed. Each list has at most 12 reading ids. |
classes | list | any | Classes that fit. 1 to 8 names of lower-case letters, digits and underscores. The class set in Homey counts too. |
Reading ids look like Homey’s: lower-case letters, digits and underscores, with one optional sub-capability after a dot, as in measure_power.phase1.
The template reads it like the tile’s own device, with a cap of its own: settings.pump.name, settings.pump.cap.measure_power.text.
It is null until a fitting device is chosen, and again if the device is gone or no longer fits.
{ "type": "device", "name": "charger", "label": "Charger", "help": "The charger the car is plugged into", "requires": { "all": ["evcharger_charging"], "any": ["measure_power", "meter_power"] }, "classes": ["evcharger"]}capability
One reading.
| Option | Type | Default | Rules |
|---|---|---|---|
of | text | the tile’s own device | The name of a device setting of this widget whose reading it is. |
kinds | list | any | Only readings of these kinds are offered: number, boolean, enum or string. At least one. |
setable | yes/no | any | Only readings that can be changed are offered, for a control. |
The template reads it like cap.<id>, with an id as well: settings.reading.text, settings.reading.id.
Written whole into an attribute, it is a live reference.
It is null when nothing is chosen.
{ "type": "capability", "name": "reading", "label": "Reading", "of": "charger", "kinds": ["number"]}flow, mood and dashboard
These take only the common fields.
A flow reads as an object with id, name and a few more details, a mood has id, name and zone, and a dashboard has id and name.
They are null until one is chosen.
{ "type": "flow", "name": "boost", "label": "Boost flow", "required": false }Several at once (multiple)
A device, flow, mood or dashboard setting can hold a list instead of one.
Use it for “all my smoke detectors” instead of eight device settings.
| Option | Type | Default | Rules |
|---|---|---|---|
multiple | yes/no | false | Makes the setting a list. |
min | number | 1 when required, else 0 | The fewest a tile picks, 1 to 32. Only on a list that is required. |
max | number | 32 | The most a tile picks, 1 to 32, and not below min. |
min and max only go with multiple.
The template reads a list as a list, in the order the tile picked them.
Each device in it reads like a device setting, with its own cap and pending, and each flow, mood or dashboard like its single setting.
Picked ones that are gone or no longer fit are left out.
{% for alarm in settings.alarms %} <p>{{ alarm.zone }}: {{ alarm.cap.alarm_smoke.text }}</p>{% else %} <p>No smoke detectors chosen.</p>{% endfor %}A list is never null: with nothing picked it is empty.
Liquid counts an empty list as true, so test {% if settings.alarms.size > 0 %}, not {% if settings.alarms %}.
settings.alarms.first and settings.alarms[0] read one of them.
For a device list, each tile picks its devices in an order, or takes every device that fits.
That way a smoke detector added to Homey later shows up by itself.
Those are sorted by zone, then by name, and at most max of them are shown.
A tile stores a list of ids, or { "every": true } for every device that fits.
A setting that was one device and became a list keeps the device a tile picked.
A capability’s or a tap’s of has to name a single device setting, not a list.
Read a list’s readings in the loop instead: alarm.cap.measure_battery.text.
{ "type": "device", "name": "alarms", "label": "Smoke detectors", "multiple": true, "max": 12, "requires": { "all": ["alarm_smoke"] }}Simple values
Each of these has a default, so the widget works before anything is chosen, except where noted.
number
A number, as a slider, a stepper or a plain field. In the editor it is A number.
| Option | Type | Default | Rules |
|---|---|---|---|
default | number | none | Required. Has to be within min and max. |
min | number | none | The lowest value. Not above max. |
max | number | none | The highest value. |
step | number | none | The step. Above zero. |
unit | text | none | At most 12 characters, shown after the number. A CSS unit goes onto the style too. |
control | text | field | slider, stepper or field. A slider needs a min and a max. |
The template reads the number; the style reads it with its unit when it is one of px, em, rem, %, ch, ex, vw, vh, vmin, vmax, cqw, cqh, cqi, cqb, cqmin, cqmax, deg, turn, s, ms or fr.
{ "type": "number", "name": "gap", "label": "Gap", "default": 8, "min": 0, "max": 24, "step": 2, "unit": "px", "control": "slider"}percentage
A number from 0 to 100, as a slider.
The default is required, from 0 to 100.
The style reads it as 62%.
{ "type": "percentage", "name": "glow", "label": "Glow", "default": 60 }boolean
Yes or no, as a switch.
The default is required.
The template reads true or false, and the style reads 1 or 0.
{ "type": "boolean", "name": "showWarmth", "label": "Colour temperature slider", "default": true }text
| Option | Type | Default | Rules |
|---|---|---|---|
default | text | none | Required. At most 400 characters, and no longer than maxLength. |
maxLength | number | 80 | A whole number from 1 to 400. |
multiline | yes/no | false | Several lines instead of one. |
placeholder | text | none | At most 80 characters. |
A required text that is left empty falls back to its default.
An optional one that is left empty is null, so {% if settings.title %} and default: agree.
{ "type": "text", "name": "title", "label": "Title", "default": "Garden", "maxLength": 30 }choice
One of a list of options. In the editor it is A choice.
| Option | Type | Default | Rules |
|---|---|---|---|
options | list | none | Required. 2 to 12 options, each with a value (1 to 40 letters, digits, underscores or dashes) and a label (1 to 40 characters). Every value is different. |
default | text | none | Required. One of the option values. |
control | text | auto | dropdown, segmented or auto, which is segmented up to four options. |
The template reads the chosen value, which is always one of the options.
{ "type": "choice", "name": "layout", "label": "Layout", "options": [ { "value": "compact", "label": "Compact" }, { "value": "roomy", "label": "Roomy" } ], "default": "roomy"}color
A colour: a theme colour by name (accent, lit, cool, good, warn, danger, text, surface, canvas, chart-1 to chart-6) or a fixed #rrggbb.
The default is optional.
Without one, nothing is chosen until the tile picks, and the template reads null.
The style reads a theme colour as its variable (var(--hd-lit)) and a fixed colour as #rrggbb.
{ "type": "color", "name": "accent", "label": "Accent colour", "default": "lit", "group": "look" }icon
An icon from the icon library, written like device.light.
The default is optional, and without one the template reads null until the tile picks.
The template passes it to hd-icon, and the style reads it as a quoted string.
{ "type": "icon", "name": "symbol", "label": "Icon", "default": "device.light" }size
small, medium or large, with a required default.
The template reads the word.
The style reads the word, and -scale adds 0.85, 1 or 1.25.
{ "type": "size", "name": "titleSize", "label": "Title size", "default": "medium", "group": "look" }spot
One of the tile’s nine spots, chosen on a small grid: top-left, top-center, top-right, middle-left, middle-center, middle-right, bottom-left, bottom-center or bottom-right.
The default is required.
Both the template and the style read the name.
{ "type": "spot", "name": "titleSpot", "label": "Title position", "default": "top-left", "group": "look"}Kinds for bigger jobs
These are the settings the built-in widgets use for their lists and special controls. Each keeps the editor that the built-in widget has for it.
readings
A list of readings of any devices, with the range to show them over, for charts.
Template: settings.<name>.items, a list whose entries have cap (the reading, which renders as its live reference), label, device and ref, and settings.<name>.range.
| Option | Type | Default | Rules |
|---|---|---|---|
max | number | 6 | A whole number from 1 to 8. |
kinds | list | ["number"] | number and boolean. At least one. |
range | text | none | The range the tile’s owner picks from, starting here: 6h, 12h, 24h, 7d, 30d or 1y. Left out, they pick none. |
<hd-chart range="{{ settings.lines.range }}"> {% for r in settings.lines.items %} <hd-series bind="{{ r.cap }}" label="{{ r.label }}"></hd-series> {% endfor %}</hd-chart>values
A list of values like the Custom tile’s: each is one reading, or several added and subtracted, with a label, an icon, a colour and a place.
Template: settings.<name> is the list of worked-out values, each with label, icon, color, value, text, unit, available, exporting, bind, show, fraction, slot, size and position.
| Option | Type | Default | Rules |
|---|---|---|---|
max | number | 6 | A whole number from 1 to 12. |
kinds | list | any | Readings offered: number, boolean and text. At least one. |
Besides device readings, a value can read the Homey’s energy and prices: what today cost, electricity, gas and water used today and yesterday, solar, the home battery and the car, the top users, this week’s, month’s and year’s amounts and costs, the price now and next, today’s and tomorrow’s lowest, average and highest, and the cheapest hours ahead.
They are picked on the Energy and Prices tabs of the value picker.
A stored value names one by its key instead of a device and a capability ({ "host": "energy:cost", "sign": 1 }, prices:now, energy:gas.today), and can be added up with others like a reading.
Money and prices read with the currency in front (€3.12, €0.36 with unit /kWh), times and cheapest windows as words (Tonight 01:00–04:00).
A price’s color is price-cheap, price-normal, price-high or price-negative when the value has none of its own, and its bind is empty: energy and prices can’t be charted yet.
buttons
A list of buttons for devices, flows, moods and dashboards.
Template: settings.<name> is the list, each with kind, id, name, icon, color and on, and more for the animated glyphs.
| Option | Type | Default | Rules |
|---|---|---|---|
max | number | 12 | A whole number from 1 to 24. |
kinds | list | all four | device, flow, mood and dashboard. At least one. |
tap
What tapping or holding a part of the widget does, chosen by the tile’s owner.
Template: mark a part with data-hd-tap="<name>" or data-hd-longpress="<name>"; taps.<name> is there while the tap does something.
| Option | Type | Default | Rules |
|---|---|---|---|
gesture | text | tap | tap or longpress. |
default | object | { "type": "none" } | What it does until the owner chooses: none, toggle, history (with an optional range) or device. Has to be one that allow offers. |
allow | list | all | The actions offered: none, toggle, history, device, dashboard, flow, mood. Each once. Nothing is always offered. |
of | text | the tile’s own device | The name of a device setting whose device the part belongs to. |
capability | text | none | The reading the part shows, which toggle and history use. |
See Taps and handlers.
places
Devices that know where they are, for a map.
Template: settings.<name> is the list, each with id, name, lat, lon, icon, since and stale.
| Option | Type | Default | Rules |
|---|---|---|---|
max | number | 10 | A whole number from 1 to 20. |
energy
The parts of the Homey’s energy flow, found on each Homey.
It takes only the common fields.
Template: settings.<name> has grid, solar, battery, batteryCharge, car, carCharge (watts, or null for a part that isn’t there), todaySolar, todayUsed and todayExported (kWh), and parts, the number of parts shown.
busy
The things that are busy now: appliances, chargers and plugs.
Template: settings.<name> is the list of those busy, each with id, name, glyph, state (running or done), since, text, power and tap.
| Option | Type | Default | Rules |
|---|---|---|---|
max | number | 8 | A whole number from 1 to 16. |
keepDone | text | none | The name of a choice setting of this widget that says how many minutes a finished thing stays on the list. Left out, a quarter of an hour. |
layout
Folds a values setting into sections and tabs, and places pictures.
Its group defaults to layout.
Template: settings.<name> has loose (the values in no section or tab), sections, tabs, tabsAt, tabsLook and pictures.
| Option | Type | Default | Rules |
|---|---|---|---|
of | text | none | Required. The name of the values setting it arranges. |
pictures | yes/no | true | Whether pictures and uploads can be placed. Off, icons only. |
Draw what it gives with layout blocks.
capabilities
Which of the tile’s own device’s readings to show, ticked one by one.
Template: settings.<name> is a list of reading ids, in the device’s order.
| Option | Type | Default | Rules |
|---|---|---|---|
exclude | list | [] | Readings left out of the default selection. At most 12. |
defaultCount | number | 4 | How many of the device’s first readings show until some are ticked. 0 to 20. |
place
Where a weather widget looks: this Homey’s own place, or a place found by name or pinned on a map.
Template: { "type": "homey" } or { "type": "place", "name": …, "lat": …, "lon": … }.
The default is { "type": "homey" }.
applianceSource
What says that an appliance is running: a variable of Homey Logic, a yes or no reading of any device, or a plug’s power above a number of watts.
It takes only the common fields.
Template: settings.<name> has state (running, done or off), since, power, from and problem.
applianceIcon
How an appliance is drawn: a washer, a dryer, a dishwasher or any icon.
The default is washer, dryer or dishwasher, and washer if you leave it out.
Template: settings.<name> has kind (washer, dryer, dishwasher or icon) and icon, which is null for a machine.
A list of settings
A small widget with four settings, one of each of the most common kinds:
[ { "type": "text", "name": "title", "label": "Title", "default": "Garden", "maxLength": 30 }, { "type": "color", "name": "accent", "label": "Accent colour", "default": "lit", "group": "look" }, { "type": "number", "name": "gap", "label": "Gap", "default": 8, "min": 0, "max": 24, "unit": "px", "group": "look" }, { "type": "device", "name": "pump", "label": "Pump", "requires": { "all": ["onoff"] }, "classes": ["socket"] }]