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.

widget.compose.json

{
  "name": {
    "en": "My Widget"
  },
  "settings": [
    {
      "id": "text",
      "type": "text",
      "title": {
        "en": "Text"
      },
      "hint": {
        "en": "Your number"
      }
    },
    {
      "id": "number",
      "type": "number",
      "title": {
        "en": "Number"
      },
      "hint": {
        "en": "Your number"
      }
    }
  ]
}

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.

{
  "id": "text",
  "type": "text",
  "title": { "en": "Text" },
  "value": "My initial value",
  "hint": { "en": "My text hint." },
  "pattern": "[a-zA-Z]"
}

Textarea

string | null

This setting type allows users to input multi-line text.

{
  "id": "description",
  "type": "textarea",
  "title": { "en": "Textarea" },
  "value": "Enter your description here.",
  "hint": { "en": "Provide a detailed description." },
  "pattern": "[a-zA-Z]"
}

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.

{
  "id": "age",
  "type": "number",
  "title": { "en": "Age" },
  "value": 25,
  "hint": { "en": "Your age." },
  "min": 0,
  "max": 120
}

string | null

This setting type allows users to select a value from a predefined list.

{
  "id": "dropdown",
  "type": "dropdown",
  "title": {
    "en": "Dropdown",
    "nl": "Dropdown"
  },
  "value": "heating"
  "values": [
    {
      "id": "heating",
      "title": {
        "en": "Heating"
      }
    },
    {
      "id": "cooling",
      "title": {
        "en": "Cooling"
      }
    }
  ]
}

Checkbox

boolean | null

This setting type allows users to enable or disable a feature.

{
  "id": "checkbox",
  "type": "checkbox",
  "value": true
  "title": {
    "en": "Checkbox",
    "nl": "Checkbox"
  }
}

Autocomplete

object | null

This setting type provides an input that suggests options as the user types.

{
  "id": "composer",
  "type": "autocomplete",
  "title": {
    "en": "Composer"
  }
}

'use strict';

const Homey = require('homey');

class MyApp extends Homey.App {

  async onInit() {
    const widget = this.homey.dashboards.getWidget('my-widget')

    widget.registerSettingAutocompleteListener('composer', async (query, settings) => {
      return [
        {
          name: "Mozart",
          // Optionally provide the following properties.
          description: "..."
          image: "https://some.url/"

          // You can freely add additional properties
          // that you can access in Homey.getSettings()['mySettingId'].
          id: "mozart",
        },
        {
          name: "Amadeus",

          // You can freely add additional properties
          // that you can access in Homey.getSettings()['mySettingId'].
          id: "amadeus",
        },
      ].filter((item) => item.name.toLowerCase().includes(query.toLowerCase()));
    });
  }
}

module.exports = MyApp;

Accessing Settings

index.html

<html>

<head>
...
</head>

<body>
  <script type="text/javascript">
    function onHomeyReady(Homey) {
      Homey.ready();
    
      for (const [settingId, settingValue] of Object.entries(Homey.getSettings())) {
        // Do something with the settings...
      }
    }
  </script>
</body>

</html>

Last updated 2 days ago