Settings
Widget settings allow users to customize the behaviour of their dashboard widgets from Homey.
Widgets can have settings that users can change while selecting or editing a widget. This allows you to add some initial variables to your widgets.
Defining Settings
Every setting has a type
property that determines what values it can have and how it is presented to the user. The value
property of each setting is the initial value of the setting. The following setting types are supported:
Text
string | null
This is a single line text input whose value is a string. You can optionally validate the value using a regex pattern by adding a pattern
property.
Textarea
string | null
This setting type allows users to input multi-line text.
Number
number | null
This setting type allows users to input numerical values. The min
and max
properties are optional and can be used to define the acceptable range of values.
Dropdown
string | null
This setting type allows users to select a value from a predefined list.
Checkbox
boolean | null
This setting type allows users to enable or disable a feature.
Autocomplete
object | null
This setting type provides an input that suggests options as the user types.
Accessing Settings
Devices
Many widgets are designed to display content based on specific Homey devices. To simplify this, a dedicated devices
setting is provided, allowing users to select one or more devices. Once selected, your widget can access their IDs using Homey.getDeviceIds()
.
Configuration Options
The devices
setting includes the following required properties:
singular
(boolean, required) – Determines whether users can select multiple devices:false
– Allows selecting multiple devices.true
– Restricts selection to a single device.
type
(string, required) – Defines the scope of selectable devices:"app"
– Limits selection to devices belonging to your app."global"
– Allows selection from all Homey devices, only makes sense if the app has the necessaryhomey:manager:api
permission.
Additionally, an optional filter
property can be used to limit the selection to specific devices:
filter
(object, optional) – Defines selection criteria:class
(string, optional) – Filters devices by their device class (e.g.,"socket"
,"light"
,"sensor"
).Supports multiple values using a pipe (
|
) as an OR separator (e.g.,"socket|light"
allows selecting both sockets and lights).
capabilities
(string, optional) – Filters devices based on required capabilities (e.g.,"onoff"
).Supports:
OR (
|
):"onoff|dim"
→ Devices must have at least one of these capabilities.AND (
,
):"onoff,dim"
→ Devices must have all these capabilities.Combination (
|
and,
):"onoff,dim|light_mode"
→ Devices must have bothonoff
anddim
capabilities OR thelight_mode
capability.
Additionally, users can reorder selected devices via drag-and-drop.
Last updated
Was this helpful?