Homey Apps SDK
📖 Apps SDK Reference🌍 Web API🛠 Developer Tools
  • Welcome to the Apps SDK documentation 👋
  • The Basics
    • Getting Started
      • Homey CLI
    • App
      • Manifest
      • Internationalization
      • Permissions
      • Persistent Storage
    • Drivers & Devices
      • Pairing
        • System Views
          • Devices List
          • Add Devices
          • OAuth2 Login
          • Credentials Login
          • Pincode
          • Loading
          • Done
        • Custom Views
      • Capabilities
      • Energy
      • Settings
      • Best practices
        • Lights
        • Window coverings
        • Battery status
    • Flow
      • Arguments
      • Tokens
    • Widgets
      • Settings
      • Styling
      • Debugging
  • Wireless
    • Wi-Fi
      • Discovery
    • Bluetooth LE
    • Z-Wave
    • Zigbee
    • 433 MHz
    • Infrared
    • Matter
  • Cloud
    • OAuth2
    • Webhooks
  • App Store
    • Publishing
    • Guidelines
    • Verified Developer
    • Updating
  • Advanced
    • Custom Views
      • App Settings
      • Custom Pairing Views
      • HTML & CSS Styling
    • Web API
    • Images
    • LED Ring
    • Homey Compose
  • Guides
    • Homey Cloud
    • Breaking Changes
    • Tools
      • Bluetooth LE
      • Zigbee
      • TypeScript
    • Using ESM in Homey Apps
  • Upgrade Guides
    • Homey v6.0.0
    • Upgrading to SDK v3
      • Zigbee Apps
    • Device Capabilities
Powered by GitBook
On this page
  • Defining Settings
  • Text
  • Textarea
  • Number
  • Dropdown
  • Checkbox
  • Autocomplete
  • Accessing Settings
  • Devices

Was this helpful?

  1. The Basics
  2. Widgets

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
}

Dropdown

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>

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 necessary homey: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 both onoff and dim capabilities OR the light_mode capability.

Additionally, users can reorder selected devices via drag-and-drop.

widget.compose.json
{
  "name": {
    "en": "My Widget"
  },
  "devices": {
    "type": "global",
    "singular": false,
    "filter": {
      "class": "socket",
      "capabilities": "onoff"
    }
  },
  "settings": [
    {
      "id": "text",
      "type": "text",
      "title": {
        "en": "Text"
      },
      "hint": {
        "en": "Your number"
      }
    },
    {
      "id": "number",
      "type": "number",
      "title": {
        "en": "Number"
      },
      "hint": {
        "en": "Your number"
      }
    }
  ]
}

PreviousWidgetsNextStyling

Last updated 2 months ago

Was this helpful?