Selectors


Selectors can be used to specify what values are accepted for a blueprint input. The selector also defines how the input is shown in the user interface.

Some selectors can, for example, show a toggle button to turn something on or off, while another select can filter a list of devices to show only devices that have motion-sensing capabilities.

Having good selectors set on your blueprint automation inputs makes a blueprint easier to use from the UI.

The following selectors are currently available:

Interactive demos of each of these selectors can be found on the Home Assistant Design portal.

If no selector is defined, a text input for a single line will be shown.

Action selector

The action selector allows the user to input one or more sequences of actions. On the user interface, the action part of the automation editor will be shown. The value of the input will contain a list of actions to perform.

Screenshot of an action selector

This selector does not have any other options; therefore, it only has its key.

action:

The output of this selector is a list of actions. For example:

# Example Action selector output result
- service: scene.turn_on
  target:
    entity_id: scene.watching_movies
  metadata: {}

Add-on selector

This can only be used on an installation with a Supervisor. For installations that do not have that, an error will be displayed.

The add-on selector allows the user to input an add-on slug. On the user interface, it will list all installed add-ons and use the slug of the selected add-on.

Screenshot of an add-on selector

This selector does not have any other options; therefore, it only has its key.

# Example Add-on selector
addon:

The output of this selector is the slug of the selected add-on. For example: core_ssh.

Area selector

The area selector shows an area finder that can pick a single or multiple areas based on the selector configuration. The value of the input will be the area ID, or a list of area IDs, based on if multiple is set to true.

An area selector can filter the list of areas, based on properties of the devices and entities that are assigned to those areas. For example, the areas list could be limited to areas with entities provided by the ZHA integration.

In its most basic form, this selector doesn’t require any options, which will show all areas.

Screenshot of an area selector

area:

Configuration Variables

device list (Optional)

When device options are provided, the list of areas is filtered by areas that at least provide one device that matches the given conditions. Can be either a object or a list of object.

integration string (Optional)

Can be set to an integration domain. Limits the list of areas that provide devices by the set integration domain, for example, zha.

manufacturer string (Optional)

When set, it limits the list of areas that provide devices by the set manufacturer name.

model string (Optional)

When set, it limits the list of areas that provide devices that have the set model.

entity list (Optional)

When entity options are provided, the list of areas is filtered by areas that at least provide one entity that matches the given conditions. Can be either a object or a list of object.

integration string (Optional)

Can be set to an integration domain. Limits the list of areas that provide entities by the set integration domain, for example, zha.

domain string | list (Optional)

Limits the list of areas that provide entities of a certain domain(s), for example, light or binary_sensor. Can be either a string with a single domain, or a list of string domains to limit the selection to.

device_class device_class | list (Optional)

Limits the list of areas to areas that have entities with a certain device class(es), for example, motion or window. Can be either a string with a single device_class, or a list of string device_class to limit the selection to.

supported_features list (Optional)

Limits the list of areas to areas that have entities with a certain supported feature, for example, light.LightEntityFeature.TRANSITION or climate.ClimateEntityFeature.TARGET_TEMPERATURE. Should be a list of features.

multiple boolean (Optional, default: false)

Allows selecting multiple areas. If set to true, the resulting value of this selector will be a list instead of a single string value.

The output of this selector is the area ID, or (in case multiple is set to true) a list of area IDs.

# Example Area selector output result, when multiple is set to false
living_room

# Example Area selector output result, when multiple is set to true
- living_room
- kitchen

Example area selectors

An example area selector only shows areas that provide one or more lights or switches provided by the ZHA integration.

area:
  entity:
    integration: zha
    domain:
      - light
      - switch

Another example uses the area selector, which only shows areas that provide one or more remote controls provided by the deCONZ integration. Multiple areas can be selected.

area:
  multiple: true
  device:
    - integration: deconz
      manufacturer: IKEA of Sweden
      model: TRADFRI remote control

Attribute selector

The attributes selector shows a list of state attributes from a provided entity of which one can be selected.

This allows for selecting, e.g., the “Effect” attribute from a light entity, or the “Next dawn” attribute from the sun entity.

Screenshot of an attribute selector

Configuration Variables

entity_id string Required

The entity ID of which an state attribute can be selected from.

The output of this selector is the selected attribute key (not the translated or prettified name shown in the frontend). For example: next_dawn.

Assist pipeline selector

The assist pipeline selector shows all available assist pipelines (assistants) of which one can be selected.

Screenshot of an assist pipeline selector

This selector does not have any other options; therefore, it only has its key.

assist_pipeline:

Backup location selector

This can only be used on an installation with a Supervisor (Operating System or Supervised). For installations of type Home Assistant Core or Container, an error will be displayed.

The backup location selector shows a list of places a backup could go, depending on what you have configured in storage.

Screenshot of an assist pipeline selector

The output of this selector is the name of the selected network storage. It may also be the value /backup, if the user chooses to use the local data disk option instead of one of the configured network storage locations.

Boolean selector

The boolean selector shows a toggle that allows the user to turn on or off the selected option.

Screenshot of a boolean selector

The boolean selector is suitable for adding feature switches to, for example, blueprints.

This selector does not have any other options; therefore, it only has its key.

boolean:

The output of this selector is true when the toggle is on, false otherwise.

Color temperature selector

The color temperature selector provides a select that allows for selecting a color temperature. The selector returns the number of mireds selected and allows limiting the range of selectable mireds.

Screenshot of the Color temperature selector

color_temp:

Configuration Variables

min_mireds integer (Optional, default: 153)

The minimum color temperature in mireds.

max_mireds integer (Optional, default: 500)

The maximum color temperature in mireds.

The output of this selector is the number of mired selected, for example, 243.

Condition selector

The condition selector allows the user to input one or more conditions. On the user interface, the condition part of the automation editor will be shown. The value of the input will contain a list of conditions.

Screenshot of an condition selector

This selector does not have any other options; therefore, it only has its key.

condition:

The output of this selector is a list of conditions. For example:

# Example Condition selector output result
- condition: numeric_state
  entity_id: "sensor.outside_temperature"
  below: 20

Config entry selector

The config entry selector allows the user to select an integration configuration entry. The selector returns the entry ID of the selected integration configuration entry.

Screenshot of the Configuration entry selector

config_entry:

Configuration Variables

integration string (Optional)

Limits the list of selectable configuration entries to a single integration domain.

The output of this selector is the entry ID of the config entry, for example, 6b68b250388cbe0d620c92dd3acc93ec.

Constant selector

The constant selector shows a toggle that allows the user to enable the selected option. This is similar to the boolean selector, the difference is that the constant selector has no value when it’s not enabled.

Screenshot of a constant selector

The selector’s value must be configured, and optionally, a label.

constant:
  value: true
  label: Enabled

The output of this selector is the configured value when the toggle is on, it has no output otherwise.

Conversation agent selector

The conversation agent selector allows picking a conversation agent.

Screenshot of a conversation agent selector

The selector has 1 option, language. This filters the conversation agents shown, depending on the language.

conversation_agent:
  language: en

Configuration Variables

language string (Optional)

Limits the list of conversation agents to those supporting the specified language.

The output of this selector is the ID of the conversation agent.

Date selector

The date selector shows a date input that allows the user to specify a date.

Screenshot of the Date selector

This selector does not have any other options; therefore, it only has its key.

date:

The output of this selector will contain the date in Year-Month-Day (YYYY-MM-DD) format, for example, 2022-02-22.

Date & time selector

The date selector shows a date and time input that allows the user to specify a date with a specific time.

Screenshot of the Date & time selector

This selector does not have any other options; therefore, it only has its key.

datetime:

The output of this selector will contain the date in Year-Month-Day (YYYY-MM-DD) format and the time in 24-hour format, for example: 2022-02-22 13:30:00.

Device selector

The device selector shows a device finder that can pick a single or multiple devices based on the selector configuration. The value of the input will contain the device ID or a list of device IDs, based on if multiple is set to true.

A device selector can filter the list of devices, based on things like the manufacturer or model of the device, the entities the device provides or based on the domain that provided the device.

Screenshot of a device selector

In its most basic form, this selector doesn’t require any options, which will show all devices.

device:

Configuration Variables

entity list (Optional)

When entity options are provided, the list of devices is filtered by devices that at least provide one entity that matches the given conditions. Can be either a object or a list of object.

integration string (Optional)

Can be set to an integration domain. Limits the list of devices that provide entities by the set integration domain, for example, zha.

domain string (Optional)

Limits the list of devices that provide entities of a certain domain(s), for example, light or binary_sensor. Can be either a string with a single domain, or a list of string domains to limit the selection to.

device_class device_class | list (Optional)

Limits the list of devices to devices that have entities with a certain device class(es), for example, motion or window. Can be either a string with a single device_class, or a list of string device_class to limit the selection to.

supported_features list (Optional)

Limits the list of devices to devices that have entities with a certain supported feature, for example, light.LightEntityFeature.TRANSITION or climate.ClimateEntityFeature.TARGET_TEMPERATURE. Should be a list of features.

filter list (Optional)

When filter options are provided, the list of devices is filtered by devices that at least provide one entity that matches the given conditions. Can be either a object or a list of object.

integration string (Optional)

Can be set to an integration domain. Limits the list of devices to devices provided by the set integration domain.

manufacturer string (Optional)

When set, it limits the list of devices to devices provided by the set manufacturer name.

model string (Optional)

When set, it limits the list of devices to devices that have the set model.

multiple boolean (Optional, default: false)

Allows selecting multiple devices. If set to true, the resulting value of this selector will be a list instead of a single string value.

The output of this selector is the device ID, or (in case multiple is set to true) a list of devices IDs.

# Example Device selector output result, when multiple is set to false
faadde5365842003e8ca55267fe9d1f4

# Example Device selector output result, when multiple is set to true
- faadde5365842003e8ca55267fe9d1f4
- 3da77cb054352848b9544d40e19de562

Example device selector

An example entity selector that, will only show devices that are:

  • Provided by the deCONZ integration.
  • Are a Philips Hue Remote of Model RWL021.
  • Provide a battery sensor.

And this is what is looks like in YAML:

device:
  filter:
    - integration: deconz
      manufacturer: Philips
      model: RWL021  
  entity:
    - domain: sensor
      device_class: battery

Duration selector

The duration select allow the user to select a time duration. This can be helpful for, e.g., delays or offsets.

Screenshot of the Duration selector

duration:

Configuration Variables

enable_day boolean (Optional, default: false)

When true, the duration selector will allow selecting days.

The output of this selector is a mapping of the time values the user selected. For example:

days: 1 # Only when enable_day was set to true
hours: 12
minutes: 30
seconds: 15

Entity selector

The entity selector shows an entity finder that can pick a single entity or a list of entities based on the selector configuration. The value of the input will contain the entity ID, or list of entity IDs, based on if multiple is set to true.

An entity selector can filter the list of entities, based on things like the class of the device, the domain of the entity or the domain that provided the entity.

Screenshot of an entity selector

In its most basic form, this selector doesn’t require any options, which will show all entities.

entity:

Configuration Variables

exclude_entities list (Optional)

List of entity IDs to exclude from the selectable list.

include_entities list (Optional)

List of entity IDs to limit the selectable list to.

filter list (Optional)

When filter options are provided, the entities are limited by entities that at least match the given conditions. Can be either an object or a list of objects.

integration string (Optional)

Can be set to an integration domain. Limits the list of entities to entities provided by the set integration domain, for example, zha.

domain string | list (Optional)

Limits the list of entities to entities of a certain domain(s), for example, light or binary_sensor. Can be either a string with a single domain, or a list of string domains to limit the selection to.

device_class device_class | list (Optional)

Limits the list of entities to entities that have a certain device class(es), for example, motion or window. Can be either a string with a single device_class, or a list of string device_class to limit the selection to.

supported_features list (Optional)

Limits the list of entities to entities that have a certain supported feature, for example, light.LightEntityFeature.TRANSITION or climate.ClimateEntityFeature.TARGET_TEMPERATURE. Should be a list of features.

multiple boolean (Optional, default: false)

Allows selecting multiple entities. If set to true, the resulting value of this selector will be a list instead of a single string value.

The output of this selector is the entity ID, or (in case multiple is set to true) a list of entity IDs.

# Example entity selector output result, when multiple is set to false
light.living_room

# Example entity selector output result, when multiple is set to true
- light.living_room
- light.kitchen

Example entity selector

An example entity selector that, will only show entities that are:

  • Provided by the ZHA integration.
  • From the Binary Sensor domain.
  • Have presented themselves as devices of a motion device class.
  • Allows selecting one or more entities.

And this is what it looks like in YAML:

entity:
  multiple: true
  filter:
    - integration: zha
      domain: binary_sensor
      device_class: motion

Icon selector

The icon selector shows an icon picker that allows the user to select an icon.

icon:

Configuration Variables

placeholder string (Optional)

Placeholder icon to show, when no icon is selected.

The output of this selector is a string containing the selected icon, for example: mdi:bell.

Language selector

The language selector allows a user to pick a language from a list of languages.

Screenshot of an language selector

language:

Configuration Variables

languages list (Optional)

A list of languages to pick from, this should be RFC 5646 languages codes.

Default:

The available languages in the Home Assistant frontend

native_name boolean (Optional, default: false)

Should the name of the languages be shown in the language of the user, or in the language itself.

no_sort boolean (Optional, default: false)

Should the options be sorted by name, if set to true, the order of the provided languages is kept.

The output of this selector is a RFC 5646 language code.

Location selector

The location selector allow a user to pick a location from a map and returns the matching longitude and latitude coordinators. Optionally it supports selecting the radius of the location.

Screenshot of the Location selector

location:

Configuration Variables

icon string (Optional)

An optional icon to show on the map.

radius boolean (Optional, default: false)

Allow selecting the radius of the location. If enabled, the radius will be returned in meters.

The output of this selector is a mapping containing the latitude and longitude of the selected location, and, if enabled, the radius. For example:

latitude: 50.935
longitude: 6.95
radius: 500 # Only provided when radius was set to true.

Media selector

The media selector is a powerful selector that allows a user to easily select media to play on a media device. Media can be a lot of things, for example, cameras, local media, text-to-speech, Home Assistant Dashboards, and many more.

The user selects the device to play media on, and automatically limits the selectable media suitable for the selected device.

Screenshot of the Media selector

media:

The output of the media selector, is an mapping with information about the selected media device and the selected media to play. There is also metadata, which is used by the frontend and should not be used in the backend.

Example output:

entity_id: media_player.living_room
media_content_id: media-source://tts/cloud?message=TTS+Message&language=en-US&gender=female
media_content_type: provider
metadata:
  title: TTS Message
  thumbnail: https://brands.home-assistant.io/_/cloud/logo.png
  media_class: app
  children_media_class: null
  navigateIds:
    - {}
    - media_content_type: app
      media_content_id: media-source://tts
    - media_content_type: provider
      media_content_id: >-
        media-source://tts/cloud?message=TTS+Message&language=en-US&gender=female

Number selector

The number selector shows either a number input or a slider input, that allows the user to specify a numeric value. The value of the input will contain the select value.

Screenshot of a number selector

On the user interface, the input can either be in a slider or number mode. Both modes limit the user input by a minimum and maximum value, and can have a unit of measurement to go with it.

In its most basic form, this selector requires a minimum and maximum value:

number:
  min: 0
  max: 100

Configuration Variables

min integer | float Required

The minimum user-settable number value.

max integer | float Required

The maximum user-settable number value.

step integer | float | any (Optional, default: 1)

The step size of the number value. Set to "any" to allow any number.

unit_of_measurement string (Optional)

Unit of measurement in which the number value is expressed in.

mode string (Optional, default: slider)

This can be either box or slider mode.

The output of this selector is a number, for example: 42

Example number selectors

An example number selector that allows a user a percentage, directly in a regular number input box.

number:
  min: 0
  max: 100
  unit_of_measurement: "%"

A more visual variant of this example could be achieved using a slider. This can be helpful for things like allowing the user to select a brightness level of lights. Additionally, this example changes the brightness in incremental steps of 10%.

number:
  min: 0
  max: 100
  step: 10
  unit_of_measurement: "%"
  mode: slider

Object selector

The object selector can be used to input arbitrary data in YAML form. This is useful for e.g. lists and dictionaries like service data. The value of the input will contain the provided data.

Screenshot of an object selector

This selector does not have any other options; therefore, it only has its key.

object:

The output of this selector is a YAML object.

RGB color selector

The RGB color selector allows the user to select an color from a color picker from the user interface, and returns the RGB color value.

Screenshot of the RGB Color selector

color_rgb:

This selector does not have any other options; therefore, it only has its key.

The output of this selector is a list with the three (RGB) color value, for example: [255, 0, 0].

Select selector

The select selector shows a list of available options from which the user can choose. The value of the input contains the value of the selected option. Only a single option can be selected at a time.

Screenshot of a select selector

The selector requires a list of options that the user can choose from.

select:
  options:
    - Red
    - Green
    - Blue

Configuration Variables

options list Required

List of options that the user can choose from. Small lists (5 items or less), are displayed as radio buttons. When more items are added, a dropdown list is used.

multiple boolean (Optional, default: false)

Allows selecting multiple options. If set to true, the resulting value of this selector will be a list instead of a single string value.

custom_value boolean (Optional, default: false)

Allows the user to enter and select a custom value (or multiple custom values in addition to the listed options if multiple is set to true).

mode string (Optional)

This can be either list (radio buttons) or dropdown (combobox) mode. When not specified, small lists (5 items or less), are displayed as radio buttons. When more items are added, a dropdown list is used. If custom_value is true, this setting will be ignored and the frontend will use a dropdown input.

translation_key string (Optional)

Allows translations provided by an integration where translation_key is the translation key that is providing the selector option strings translation. See the documentation on Backend Localization for more information.

sort boolean (Optional, default: false)

Display options in alphabetical order.

Alternatively, a mapping can be used for the options. When you want to return a different value compared to how it is displayed to the user.

select:
  options:
    - label: Red
      value: r
    - label: Green
      value: g
    - label: Blue
      value: b

Configuration Variables

options map Required

List of options that the user can choose from. Small lists (5 items or less), are displayed as radio buttons. When more items are added, a dropdown list is used.

label string Required

The description to show in the UI for this item.

value string Required

The value to return when this label is selected.

When multiple is false, the output of this selector is the string of the selected option value. When selecting Green in the last example, it returns: g, in the first example it would return Green.

When multiple is true, the output of this selector is the list of selected option values. In this case, if Green was selected, in the first example it would return [“Green”] and in the last example it returns [“g”].

State selector

The state selector shows a list of states for a provided entity of which one can be selected.

Screenshot of an state selector

Configuration Variables

entity_id string Required

The entity ID of which an state can be selected from.

The output of this selector is the select state (not the translated or prettified name shown in the frontend).

For example: heat_cool.

Target selector

The target selector is a rather special selector, allowing the user to select targeted entities, devices or areas for service calls. The value of the input will contain a special target format, that is accepted by service calls.

The selectable targets can be filtered, based on entity or device properties. Areas are only selectable as a target, if some entities or devices match those properties in those areas.

Screenshot of a target selector

In its most basic form, this selector does not require any options, which will allow the user to target any entity, device or area available in the system.

target:

Configuration Variables

device list

When device options are provided, the targets are limited by devices that at least match the given conditions. Can be either a object or a list of object.

integration string (Optional)

Can be set to an integration domain. Limits the device targets that are provided devices by the set integration domain, for example, zha.

manufacturer string (Optional)

When set, it limits the targets to devices provided by the set manufacturer name.

model string (Optional)

When set, it limits the targets to devices by the set model.

entity list (Optional)

When entity options are provided, the targets are limited by entities that at least match the given conditions. Can be either a object or a list of object.

integration string (Optional)

Can be set to an integration domain. Limits targets to entities provided by the set integration domain, for example, zha.

domain string | list (Optional)

Limits the targets to entities of a certain domain(s), for example, light or binary_sensor. Can be either a with a single domain, or a list of string domains to limit the selection to.

device_class device_class | list (Optional)

Limits the targets to entities with a certain device class(es), for example, motion or window. Can be either a string with a single device_class, or a list of string device_class to limit the selection to.

Targets are meant to be used with the target property of a service call in a script sequence. For example:

action:
  - service: light.turn_on
    target: !input lights

Example target selectors

An example target selector that only shows targets that at least provide one or more lights, provided by the ZHA integration.

target:
  entity:
    - integration: zha
      domain: light

Another example using the target selector, which only shows targets that provide one or more remote controls, provided by the deCONZ integration.

target:
  device:
    - integration: deconz
      manufacturer: IKEA of Sweden
      model: TRADFRI remote control

Template selector

The template selector can be used to input a Jinja2 template. This is useful for allowing more advanced user-input that use Jinja2 templates.

Screenshot of an template selector

This selector does not have any other options; therefore, it only has its key.

template:

The output of this selector is a template string.

Text selector

The text selector can be used to input a text string. The value of the input will contain the selected text.

Screenshot of text selectors

Unless multiline is set to true, this selector behaves exactly like if no selector at all was specified, and will display a single line text input box on the user interface.

text:

Configuration Variables

multiline boolean (Optional, default: false)

Set to true to display the input as a multi-line text box on the user interface.

prefix string (Optional)

An optional prefix to show before the text input box.

suffix string (Optional)

An optional suffix to show after the text input box.

type string (Optional, default: text)

The type of input. This supplies the HTML type attribute, which controls how the browser displays and validates the field. A subset of types available to the attribute are supported, since some are handled by other selectors. Possible types are: color, date, datetime-local, email, month, number, password, search, tel, text, time, url, week.

autocomplete string (Optional)

Guides the browser on the type of information which should automatically fill the field. This supplies the HTML autocomplete attribute. Any value supported by the HTML attribute is valid.

The output of this selector is a single string value.

Theme selector

The theme selector allows for selecting a theme from the available themes installed in Home Assistant.

Screenshot of the Theme selector

theme:

Configuration Variables

include_default boolean (Optional, default: false)

Includes Home Assistant default theme in the list.

The output of this selector will contain the selected theme, for example: waves_dark.

Time selector

The time selector shows a time input that allows the user to specify a time of the day.

Screenshot of a time selector

This selector does not have any other options; therefore, it only has its key.

time:

The output of this selector will contain the time in 24-hour format, for example, 23:59:59.