Manifest

The manifest is the part of a widget that says what it is: its name, the devices it fits, the sizes its tile can have and the settings each tile can change. The template and the style say what it shows and how.

You don’t write a manifest by hand in the app. The editor builds the manifest of a widget of yours from what you give it, and the rest comes from the widget you started from. This page lists every field, so you know what is behind the editor and can read the manifest of a built-in widget.

Fields

type

A lower-case name in at least two parts joined by dots. Each part starts with a letter and continues with letters, digits and dashes. light.basic and sensor.motion-light are valid; light and Light.Basic are not.

The pattern is ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$.

Tiles of a widget of yours refer to it as own: followed by its id.

version

Three numbers joined by dots: 1.0.0, 2.13.4. The pattern is ^\d+\.\d+\.\d+$. A widget you copied from a built-in remembers the version it was copied at, and tells you when the built-in has a newer one.

api

The version of the widget API, which is the list of components, attributes, filters and actions a template may use. It is 1, and nothing else is accepted.

title and description

title is 1 to 60 characters. description is at most 240 characters. For a widget of yours the title is its name, and the description is the line you write under In the widget picker on the Details panel.

kind

A widget that starts empty is free.

match

Says which devices the widget fits, and ranks widgets for the picker, so that the most specific one is suggested first. A device class together with readings is the most specific, a class alone comes next, then a single reading, and a widget that matches anything comes last.

A widget of yours has the match of the widget it started from.

size

A tile is measured in grid cells: [columns, rows]. Columns are 1 to 12 and rows are 1 to 24, both whole numbers. A row is half as tall as a column is wide, so [3, 4] is roughly square.

A widget of yours that started from another has that widget’s sizes. A widget that started empty gets the default and smallest size you set under Details, and a largest size of [12, 24].

settings

A list of up to 32 settings, in the order a tile’s settings show them. It is empty by default. The settings reference describes every kind.

align

Where the widget’s content can sit in the tile. The tile’s Style panel offers these directions and no others, and each one has a place that is used until the tile says otherwise. The content reads the choice through --hd-item-align and --hd-item-justify.

Leave a direction out and it isn’t offered. No other fields are allowed.

A full manifest

This is the Light widget’s manifest:

{  "type": "light.basic",  "version": "1.2.0",  "api": 1,  "title": "Light",  "description": "Switch, brightness and colour temperature of a light.",  "kind": "device",  "match": {    "classes": ["light"],    "requires": ["onoff"],    "optional": ["dim", "light_temperature", "light_hue", "measure_power"]  },  "size": {    "default": [3, 4],    "min": [2, 4],    "max": [6, 8]  },  "settings": [    {      "type": "boolean",      "name": "showWarmth",      "label": "Colour temperature slider",      "default": true    }  ],  "align": { "x": "start", "y": "end" }}

Where a widget of yours gets each field

When you turn on Use mine instead of the built-in, your widget keeps the built-in’s type and title, so tiles that already use it keep their settings and look.