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
• Country selector
• Date selector
• Date & time selector
• Device selector
• Duration selector
• Entity selector
• Floor selector
• Icon selector
• Label selector
• Language selector
• Location selector
• Media selector
• Number selector
• Object selector
• QR code selector
• RGB color selector
• Select selector
• State selector
• Target selector
• Template selector
• Text selector
• Theme selector
• Time selector
• Trigger 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
- action: 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:

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 CoreHome Assistant Core is the heart of Home Assistant itself. It is a Python program that powers every installation type, but can be installed standalone. [Learn more] or Home Assistant ContainerHome Assistant Container is a standalone container-based installation of Home Assistant Core. Any OCI compatible runtime can be used, but the documentation focus is on Docker. [Learn more], 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.

backup_location:

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 allows you to select a color temperature from a gradient using a slider.

color_temp:

The output of this selector is the number representing the chosen color temperature for the unit used.

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.

Country selector

The country selector allows a user to pick a country from a list of countries.

country:

The output of this selector is an ISO 3166 country code.

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:

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
milliseconds: 500 # Only when enable_millisecond was set to true

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:

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

Floor selector

The floor selector shows a floor finder that can pick floors based on the selector configuration. The value of the input will be the floor ID. If multiple is set to true, the value is a list of floor IDs.

A floor selector can filter the list of floors based on the properties of the devices and entities assigned to the areas on those floors. For example, the floor list could be limited to floors with entities provided by the ZHA integration, based on the areas they are in.

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

floor:

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

# Example floor selector output result, when multiple is set to false
first_floor

# Example floor selector output result, when multiple is set to true
- first_floor
- second_floor

Example floor selectors

An example floor selector only shows floors that have one or more lights or switches provided by the ZHA integration.

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

Another example using the floor selector, which only shows floors that have one or more remote controls provided by the deCONZ integration. Multiple floors can be selected.

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

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.

Label selector

The label selector shows a label finder that can pick labels. The value of the input is the label ID. If multiple is set to true, the value is a list of label IDs.

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

label:

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

# Example label selector output result, when multiple is set to false
energy_saving

# Example label selector output result, when multiple is set to true
- energy_saving
- christmas_decorations

Language selector

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

language:

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

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 containing data for actions. 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.

QR code selector

The QR code selector shows a QR code. It has no return value.

The QR code’s data must be configured, and optionally, the scale, and error correction level can be set. The scale makes the QR code bigger or smaller.

qr_code:
  data: "https://home-assistant.io"
  scale: 5
  error_correction_level: quartile

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

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

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 actions. The value of the input will contain a special target format, that is accepted by actions.

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:

actions:
  - action: 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 enter a text string. It can also be used to enter a list of text strings; if multiple is set to true. The value of the input will contain the selected text. This can be used in shopping lists, for example.

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:

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.

Trigger selector

The triggers selector allows the user to input one or more triggers. On the user interface, the trigger part of the automation editor is shown. The value of the input contains a list of triggers.

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

trigger:

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

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