User Interface Widgets

Activity and remote-entity user interfaces consist of pages with a button grid. The user places user interface items in the grid, defines their size and, depending on the item type, links them to an entity command or to an entity.

This page describes the user interface items which are bound to an entity, so called widgets, and the shared entity feature target used by the slider widget and the Remote 3 touch slider.

The data model is defined in the REST Core-API in the UserInterfaceItem object. Integration drivers only define entities; the widgets are configured by the user in the web-configurator, or provided as default user interface by a remote entity.

Item types

Entity command parameters

Icon and text items, button mappings and sequence steps send an entity command. If the command has parameters, the web-configurator shows an editor for them, based on the entity command metadata (GET /api/cfg/entity/commands in the REST Core-API). The metadata is defined per entity type. The value range of a number parameter is either a static range, or it’s loaded from the entity the command is configured for, with the same range as the slider-capable features. For example:

• set_value of a number entity: options min, max, step and unit.
• target_temperature of a climate entity: options min_temperature, max_temperature and target_temperature_step.

Value formatting

Widgets showing a numeric value, like the sensor, slider and number widgets, format the value with the effective number of decimal places:

1. The user override in the entity’s options.user.decimals, see user overrides.
2. The decimals option of the entity.
3. The automatic format of the entity type, see the value format of the sensor and number entity.

Text values of a sensor entity are shown as they are. The values of the other slider-capable features are shown as defined in the slider-capable features.

Entity feature target

An entity feature target references a numeric feature of an entity which can be read and set. It is used by:

• the slider widget in a user interface page,
• the Remote 3 touch slider configuration of an activity.

{
  "entity_id": "hass.main.light.living_room",
  "feature": "dim"
}

Slider-capable features

A slider-capable feature pairs one numeric entity attribute (read) with one entity command (write). The remote knows the value range, step and formatting of each feature. The following features can be used as entity feature target:

• Default: the feature used if the feature property of the entity feature target is not specified.
• light.color_temperature: if the light sets the color_temperature_steps option, the slider only offers this number of positions, spread evenly over 0..100 and rounded to whole numbers. E.g. 3 steps: 0, 50, 100. Without the option, the range is 0..100 with a step of 1.
• The feature must be included in the features list of the entity, except for the number.value feature which is always present.
• The feature must have a bounded value range. A number entity with option min or max set to null is unbounded and cannot be used as an entity feature target, neither for a slider widget nor for the Remote 3 touch slider. The min and max properties of a slider widget only limit the range of a feature and cannot replace a missing limit.
• ¹ Remote 3 touch slider only. The seek feature can’t be used for a slider widget: its range changes with every track, and the position moves by itself during playback. Seeking in a user interface page belongs in the media-player widget.
• 🚧 Planned feature.

Slider

The slider widget renders a horizontal or vertical slider for an entity feature target. The current value is read from the entity attribute and updated with every entity_change event. Moving the slider sends the entity command with the new value.

Configuration

The slider configuration is set in the slider property of the user interface item:

{
  "type": "slider",
  "text": "Volume",
  "slider": {
    "entity_id": "denon.avr.zone_2",
    "feature": "volume",
    "style": "bar",
    "show_value": true,
    "icon_min": "uc:volume-low",
    "icon_max": "uc:volume-high",
    "max": 60,
    "update_mode": "live"
  },
  "location": { "x": 0, "y": 5 },
  "size": { "width": 4, "height": 1 }
}

Label rules are the same as for the sensor and select widgets: if the item’s text field is set, it is used as widget label, except if show_name is true. If no label should be shown, omit text and leave show_name at false.

Orientation and size

The orientation is derived from the item size: if the height is larger than the width, the slider is vertical, otherwise horizontal. Minimum sizes are 2x1 for a horizontal slider and 1x2 for a vertical slider.

Styles

• The orientation and size rules apply to all styles. A vertical stepper has the increase button at the top.
• bar: dragging changes the value relative to the current value, by the distance moved. A tap without movement doesn’t change the value. A touch that starts on the slider belongs to the slider and doesn’t swipe the page.
• buttons: the update_mode, icon_min, icon_max, color and fill properties have no effect.
• buttons: one step is one step of the shown value. For light.dim, which is shown as 0..100 %, that is 1 % (2.55 of 0..255, rounded). For the other features it’s the step of the feature, e.g. the step option of a number entity or the target_temperature_step of a climate entity.
• The Remote 3 touch slider has no style. These properties only exist for the slider widget.

Color

The colors are roles of the Remote UI theme, not fixed color values. A theme or a design update can change the actual colors without a configuration change.

Fill

If the feature has 10 positions or fewer, e.g. light.color_temperature with color_temperature_steps 3, the slider shows the positions and snaps to the nearest one on release.

Style defaults

Limiting the range

The optional min and max properties limit the slider to a sub-range of the feature. This allows for example a “safe volume” slider which never exceeds 60, or a brightness slider which cannot switch the light off. The limits are clamped to the value range of the feature. If the current entity value is outside the slider range, the slider shows it at the nearest end.

Value updates and feedback

• While the user moves the slider, the widget shows the selected value immediately.
• After the command has been sent, the widget follows the entity attribute from the entity_change events.
• If the integration driver doesn’t confirm the new value within a few seconds, the widget falls back to the last known attribute value. Exception: number entities with option readable: false keep the last sent value.
• update_mode: live is recommended for lights and volume, on_release for setpoints and covers. The remote never sends more than one command per 200 ms in live mode.

Physical buttons

If the screen offers D-pad navigation of the user interface items and a slider widget has the focus, the left and right buttons (up and down for a vertical slider) decrease and increase the value by one step:

• number entity: decrement / increment commands.
• Other entity types: the feature command with the current value plus or minus the step size.

Number

The number widget shows a number entity either as a slider, or as a value field with decrement and increment buttons (stepper).

Configuration

The number widget configuration is set in the number property of the user interface item:

{
  "type": "number",
  "text": "Bass",
  "number": {
    "number_id": "amp-1_bass",
    "display_mode": "auto"
  },
  "location": { "x": 0, "y": 4 },
  "size": { "width": 4, "height": 1 }
}

Label rules are the same as for the sensor, select and slider widgets.

Like the sensor and select widgets, the number entity doesn’t have to be an included entity of the activity. This is different from the slider widget, whose entity feature target must be included.

Representation

• The widget’s display_mode defines the representation:

  display_mode	Representation
  auto	The effective display mode of the entity: the user override, otherwise the display_mode option of the entity, otherwise auto.
  slider	A slider.
  stepper	A value field with decrement and increment buttons.

  The widget’s slider or stepper takes precedence over the display mode of the entity, including the user override.

• An unbounded number entity, with min or max set to null, is always shown as a stepper, also with display_mode: slider.

• The slider representation is the slider widget with the defaults: style: default, color: auto and fill: auto, so the fill starts at 0 if the range spans 0.

• The value is shown with the unit and the effective number of decimal places. See value formatting.

• Decimal places are an entity setting, not a widget setting, so a value is shown the same everywhere.

• For a slider with additional settings, like limits, icons, styles or live updates, use the slider widget.

• The orientation and the minimum size of the slider representation are the same as for the slider widget.

Commands

• Stepper: the decrement and increment buttons send the decrement and increment commands. With the widget’s step set, it is sent as step parameter. Without it, the commands are sent without step, and the integration driver uses the step option of the entity.
• The widget’s step should be a multiple of the entity’s step option. The UI doesn’t round it.
• Slider: the set_value command is sent when the slider is released.
• The UI may allow entering a value directly, e.g. by tapping the value. The value is sent with the set_value command.
• If the screen offers D-pad navigation of the user interface items and the widget has the focus, the left and right buttons (up and down for a vertical slider) send the decrement and increment commands, with the widget’s step as for the stepper.

The value updates and feedback are the same as for the slider widget.

Remote 3 touch slider

The Remote 3 touch slider is configured per activity in the touch_slider option with an entity feature target. If no target is specified, the default touch slider feature is active. The same slider-capable features are supported as targets, including the touch slider only feature media_player.seek.

{
  "touch_slider": {
    "enabled": true,
    "target": {
      "entity_id": "amp-1_bass",
      "feature": "value"
    }
  }
}