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:
- Action selector
- Add-on selector
- Area selector
- Attribute selector
- Assist pipeline selector
- Backup location selector
- Boolean selector
- Color temperature selector
- Condition selector
- Config entry selector
- Constant selector
- Conversation agent selector
- Date selector
- Date & time selector
- Device selector
- Duration selector
- Entity selector
- Icon selector
- Language selector
- Location selector
- Media selector
- Number selector
- Object selector
- RGB color selector
- Select selector
- State selector
- Target selector
- Template selector
- Text selector
- Theme selector
- Time selector
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.
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.
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.
area:
Configuration Variables
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.
Can be set to an integration domain. Limits the list of areas that provide devices by the set integration domain, for example, zha.
When set, it limits the list of areas that provide devices by the set manufacturer name.
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.
Can be set to an integration domain. Limits the list of areas that provide entities by the set integration domain, for example, zha.
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.
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.
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.
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.
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.
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.
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.
color_temp:
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.
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.
config_entry:
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.
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.
The selector has 1 option, language. This filters the conversation agents shown, depending on the language.
conversation_agent:
language: en
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.
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.
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.
In its most basic form, this selector doesn’t require any options, which will show all devices.
device:
Configuration Variables
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.
Can be set to an integration domain. Limits the list of devices that provide entities by the set integration domain, for example, zha.
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.
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.
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.
Can be set to an integration domain. Limits the list of devices to devices provided by the set integration domain.
When set, it limits the list of devices to devices provided by the set manufacturer name.
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.
duration:
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.
In its most basic form, this selector doesn’t require any options, which will show all entities.
entity:
Configuration Variables
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.
Can be set to an integration domain. Limits the list of entities to entities provided by the set integration domain, for example, zha.
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.
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.
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:
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.
language:
Configuration Variables
A list of languages to pick from, this should be RFC 5646 languages codes.
The available languages in the Home Assistant frontend
Should the name of the languages be shown in the language of the user, or in the language itself.
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.
location:
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.
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.
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
The step size of the number value. Set to "any" to allow any number.
Unit of measurement in which the number value is expressed in.
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.
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.
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.
The selector requires a list of options that the user can choose from.
select:
options:
- Red
- Green
- Blue
Configuration Variables
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.
Allows selecting multiple options. If set to true, the resulting value of this selector will be a list instead of a single string value.
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).
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.
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.
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
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.
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.
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.
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
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.
Can be set to an integration domain. Limits the device targets that are provided devices by the set integration domain, for example, zha.
When set, it limits the targets to devices provided by the set manufacturer name.
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.
Can be set to an integration domain. Limits targets to entities provided by the set integration domain, for example, zha.
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.
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.
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.
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
Set to true to display the input as a multi-line text box on the user interface.
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.
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.
theme:
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.
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.