diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index 3db79b20f77..82aa3770229 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -18,16 +18,29 @@ The following selectors are currently available: - [Action selector](#action-selector) - [Add-on selector](#add-on-selector) - [Area selector](#area-selector) +- [Attribute selector](#attribute-selector) - [Boolean selector](#boolean-selector) +- [Color temperature selector](#color-temperature-selector) +- [Date selector](#date-selector) +- [Date & time selector](#date--time-selector) - [Device selector](#device-selector) +- [Duration selector](#duration-selector) - [Entity selector](#entity-selector) +- [Icon selector](#icon-selector) +- [Location selector](#location-selector) +- [Media selector](#media-selector) - [Number selector](#number-selector) - [Object selector](#object-selector) +- [RGB color selector](#rgb-color-selector) - [Select selector](#select-selector) - [Target selector](#target-selector) - [Text selector](#text-selector) +- [Theme selector](#theme-selector) - [Time selector](#time-selector) +Interactive demos of each of these selectors can be found on the +[Home Assistant Design portal](https://design.home-assistant.io/#components/ha-selector). + If no selector is defined, a text input for a single line will be shown. ## Action selector @@ -44,6 +57,16 @@ 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: + +```yaml +# 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 @@ -58,12 +81,18 @@ selected add-on. This selector does not have any other options; therefore, it only has its key. ```yaml +# 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. +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 @@ -73,6 +102,8 @@ integration. In its most basic form, this selector doesn't require any options, which will show all areas. +![Screenshot of an area selector](/images/blueprints/selector-area.png) + ```yaml area: ``` @@ -119,10 +150,11 @@ entity: required: false domain: description: > - Limits the list of areas that provide entities of a certain domain, + Limits the list of areas that provide entities of a certain domain(s), for example, [`light`](/integrations/light) or - [`binary_sensor`](/integrations/binary_sensor). - type: string + [`binary_sensor`](/integrations/binary_sensor). Can be either a string + with a single domain, or a list of string domains to limit the selection to. + type: [string, list] required: false device_class: description: > @@ -132,37 +164,74 @@ entity: required: false multiple: description: > - Allows selecting multiple areas. + Allows selecting multiple areas. If set to `true`, the resulting value of + this selector will be a list instead of a single string value. type: boolean default: false required: false {% endconfiguration %} +The output of this selector is the area ID, or (in case `multiple` is set to +`true`) a list of area IDs. + +```yaml +# 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 -provided by the [ZHA](/integrations/zha) integration. +An example area selector only shows areas that provide one or more lights or +switches provided by the [ZHA](/integrations/zha) integration. ```yaml area: entity: integration: zha - domain: light + domain: + - light + - switch ``` Another example uses the area selector, which only shows areas that provide one or more remote controls provided by the [deCONZ](/integrations/deconz) -integration. +integration. Multiple areas can be selected. ```yaml area: + multiple: true device: - multiple: True + multiple: true integration: deconz manufacturer: IKEA of Sweden model: TRADFRI remote control ``` +## Attribute selector + +The attributes selector shows a list of state attribites 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](/images/blueprints/selector-attribute.png) + +{% configuration attribute %} +entity_id: + description: The entity ID of which an state attribute can be selected from. + type: string + required: true +{% endconfiguration %} + +The output of this selector is the selected attribute key (not the translated or +prettified name shown in the frontend). +For example: `next_dawn`. + ## Boolean selector The boolean selector shows a toggle that allows the user to turn on or off @@ -180,9 +249,72 @@ 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 was 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](/images/blueprints/selector-color-temp.png) + +```yaml +color_temp: +``` + +{% configuration color_temp %} +min_mireds: + description: The minimum color temperature in mireds. + type: integer + default: 153 + required: false +max_mireds: + description: The maximum color temperature in mireds. + type: integer + default: 500 + required: false +{% endconfiguration %} + +The output of this selector is the number of mired selected, for example, `243`. + +## Date selector + +The date selector shows a date input that allows the user to specify a date. + +![Screenshot of the Date selector](/images/blueprints/selector-date.png) + +This selector does not have any other options; therefore, it only has its key. + +```yaml +date: +``` + +The output of this selector is 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](/images/blueprints/selector-datetime.png) + +This selector does not have any other options; therefore, it only has its key. + +```yaml +datetime: +``` + +The output of this selector is 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. +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 @@ -231,9 +363,11 @@ entity: required: false domain: description: > - Limits the list of devices that provide entities of a certain domain, - for example, [`light`](/integrations/light) - or [`binary_sensor`](/integrations/binary_sensor). + Limits the list of devices that provide entities of a certain domain(s), + for example, [`light`](/integrations/light) or + [`binary_sensor`](/integrations/binary_sensor). Can be either a string + with a single domain, or a list of string domains to limit the selection + to. type: string required: false device_class: @@ -244,12 +378,25 @@ entity: required: false multiple: description: > - Allows selecting multiple devices. + Allows selecting multiple devices. If set to `true`, the resulting value of + this selector will be a list instead of a single string value. type: boolean default: false required: false {% endconfiguration %} +The output of this selector is the device ID, or (in case `multiple` is set to +`true`) a list of devices IDs. + +```yaml +# 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: @@ -270,10 +417,41 @@ device: 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](/images/blueprints/selector-duration.png) + +```yaml +duration: +``` + +{% configuration attribute %} +enable_days: + description: When `true`, the duration selector will allow selecting days. + type: boolean + default: false + required: false +{% endconfiguration %} + +The output of this selector is a mapping of the time values the user selected. +For example: + +```yaml +days: 1 # Only when enable_days 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. +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 @@ -289,6 +467,14 @@ entity: ``` {% configuration entity %} +exclude_entities: + description: List of entity IDs to exclude from the selectable list. + type: list + required: false +include_entities: + description: List of entity IDs to limit the selectable list to. + type: list + required: false integration: description: > Can be set to an integration domain. Limits the list of entities to entities @@ -298,10 +484,12 @@ integration: required: false domain: description: > - Limits the list of entities to entities of a certain domain, for example, + Limits the list of entities to entities of a certain domain(s), for example, [`light`](/integrations/light) or - [`binary_sensor`](/integrations/binary_sensor). - type: string + [`binary_sensor`](/integrations/binary_sensor). Can be either a string + with a single domain, or a list of string domains to limit the selection + to. + type: [string, list] required: false device_class: description: > @@ -311,12 +499,25 @@ device_class: required: false multiple: description: > - Allows selecting multiple entities. + Allows selecting multiple entities. If set to `true`, the resulting value of + this selector will be a list instead of a single string value. type: boolean default: false required: false {% endconfiguration %} +The output of this selector is the entity ID, or (in case `multiple` is set to +`true`) a list of entity IDs. + +```yaml +# 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: @@ -324,17 +525,112 @@ An example entity selector that, will only show entities that are: - Provided by the [ZHA](/integrations/zha) integration. - From the [Binary Sensor](/integrations/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: ```yaml entity: - multiple: True + multiple: true 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. + +```yaml +icon: +``` + +{% configuration entity %} +placeholder: + description: Placeholder icon to show, when no icon is selected. + type: string + required: false +{% endconfiguration %} + +The output of this selector is a string containing the selected icon, +for example: `mdi:bell`. + +## 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](/images/blueprints/selector-location.png) + +```yaml +location: +``` + +{% configuration entity %} +icon: + description: An optional icon to show on the map. + type: string + required: false +radius: + description: > + Allow selecting the radius of the location. If enabled, the radius will + be returned in meters. + type: boolean + default: false + required: false +{% endconfiguration %} + +The output of this selector is a mapping containing the latitude and longitude +of the selected location, and, if enabled, the radius. +For example: + +```yaml +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 Dashboads, 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](/images/blueprints/selector-media.png) + +```yaml +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: + +```yaml +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 @@ -380,6 +676,8 @@ mode: default: slider {% endconfiguration %} +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 @@ -418,6 +716,23 @@ 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](/images/blueprints/selector-color-rgb.png) + +```yaml +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. @@ -436,11 +751,47 @@ select: {% configuration select %} options: - description: List of options that the user can choose from. + description: > + 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. type: list required: true {% endconfiguration %} +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. + +```yaml +select: + options: + - label: Red + value: r + - label: Green + value: g + - label: Blue + value: b +``` + +{% configuration select_map %} +options: + description: > + 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. + type: map + required: true + keys: + label: + description: The description to show in the UI for this item. + required: true + type: string + value: + description: The value to return when this label is selected. + required: true + type: string +{% endconfiguration %} + +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`. + ## Target selector The target selector is a rather special selector, allowing the user to select @@ -501,10 +852,12 @@ entity: required: false domain: description: > - Limits the targets to entities of a certain domain, + Limits the targets to entities of a certain domain(s), for example, [`light`](/integrations/light) or - [`binary_sensor`](/integrations/binary_sensor). - type: string + [`binary_sensor`](/integrations/binary_sensor). Can be either a + with a single domain, or a list of string domains to limit the + selection to. + type: [string, list] required: false device_class: description: > @@ -555,7 +908,7 @@ target: The text selector can be used to input a text string. The value of the input will contain the selected text. -![Screenshot of a text selector](/images/blueprints/selector-text.png) +![Screenshot of text selectors](/images/blueprints/selector-text.png) 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. @@ -569,13 +922,42 @@ multiline: type: boolean default: false required: false +suffix: + description: An optional suffix to show after the text input box. + type: string + required: false +type: + description: > + The type of input. This is a browser hint, which can improve + the client-side validation of the input. The value isn't validated + by the backend. Possible types are: + `color`, `date`, `datetime-local`, `email`, `month`, `number`, `password`, `search`, `tel`, `text`, `time`, `url`, `week`. + type: string + required: false {% endconfiguration %} +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](/images/blueprints/selector-theme.png) + +```yaml +theme: +``` + +This selector does not have any other options; therefore, it only has its key. + +The output of this selector is 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. The value of the input will contain the time in 24-hour format, -for example, `23:59:59`. +of the day. ![Screenshot of a time selector](/images/blueprints/selector-time.png) @@ -584,3 +966,6 @@ This selector does not have any other options; therefore, it only has its key. ```yaml time: ``` + +The output of this selector is will contain the time in 24-hour format, +for example, `23:59:59`. diff --git a/source/images/blueprints/selector-action.png b/source/images/blueprints/selector-action.png index 25d4c17c539..2b91fcdb005 100644 Binary files a/source/images/blueprints/selector-action.png and b/source/images/blueprints/selector-action.png differ diff --git a/source/images/blueprints/selector-addon.png b/source/images/blueprints/selector-addon.png index e440ce95a03..18fe5212c96 100644 Binary files a/source/images/blueprints/selector-addon.png and b/source/images/blueprints/selector-addon.png differ diff --git a/source/images/blueprints/selector-area.png b/source/images/blueprints/selector-area.png new file mode 100644 index 00000000000..ef13a530268 Binary files /dev/null and b/source/images/blueprints/selector-area.png differ diff --git a/source/images/blueprints/selector-attribute.png b/source/images/blueprints/selector-attribute.png new file mode 100644 index 00000000000..898846be3cb Binary files /dev/null and b/source/images/blueprints/selector-attribute.png differ diff --git a/source/images/blueprints/selector-color-rgb.png b/source/images/blueprints/selector-color-rgb.png new file mode 100644 index 00000000000..dba7104dce1 Binary files /dev/null and b/source/images/blueprints/selector-color-rgb.png differ diff --git a/source/images/blueprints/selector-color-temp.png b/source/images/blueprints/selector-color-temp.png new file mode 100644 index 00000000000..6a46e3f003d Binary files /dev/null and b/source/images/blueprints/selector-color-temp.png differ diff --git a/source/images/blueprints/selector-date.png b/source/images/blueprints/selector-date.png new file mode 100644 index 00000000000..8966c2e3b68 Binary files /dev/null and b/source/images/blueprints/selector-date.png differ diff --git a/source/images/blueprints/selector-datetime.png b/source/images/blueprints/selector-datetime.png new file mode 100644 index 00000000000..be1d7e3d8c1 Binary files /dev/null and b/source/images/blueprints/selector-datetime.png differ diff --git a/source/images/blueprints/selector-device.png b/source/images/blueprints/selector-device.png index aa75176341b..27539fc08a2 100644 Binary files a/source/images/blueprints/selector-device.png and b/source/images/blueprints/selector-device.png differ diff --git a/source/images/blueprints/selector-duration.png b/source/images/blueprints/selector-duration.png new file mode 100644 index 00000000000..5dcb528a94e Binary files /dev/null and b/source/images/blueprints/selector-duration.png differ diff --git a/source/images/blueprints/selector-entity.png.png b/source/images/blueprints/selector-entity.png.png new file mode 100644 index 00000000000..9f124caf9c2 Binary files /dev/null and b/source/images/blueprints/selector-entity.png.png differ diff --git a/source/images/blueprints/selector-icon.png b/source/images/blueprints/selector-icon.png new file mode 100644 index 00000000000..bca6f4b1f88 Binary files /dev/null and b/source/images/blueprints/selector-icon.png differ diff --git a/source/images/blueprints/selector-location.png b/source/images/blueprints/selector-location.png new file mode 100644 index 00000000000..dfaa41c7165 Binary files /dev/null and b/source/images/blueprints/selector-location.png differ diff --git a/source/images/blueprints/selector-media.png b/source/images/blueprints/selector-media.png new file mode 100644 index 00000000000..0ccfc3830fb Binary files /dev/null and b/source/images/blueprints/selector-media.png differ diff --git a/source/images/blueprints/selector-number.png b/source/images/blueprints/selector-number.png index 8d73e008722..6b65d994b9b 100644 Binary files a/source/images/blueprints/selector-number.png and b/source/images/blueprints/selector-number.png differ diff --git a/source/images/blueprints/selector-object.png b/source/images/blueprints/selector-object.png index 3ed19fc834e..aa947d1e472 100644 Binary files a/source/images/blueprints/selector-object.png and b/source/images/blueprints/selector-object.png differ diff --git a/source/images/blueprints/selector-select.png b/source/images/blueprints/selector-select.png index 6c12c0aa9eb..51a4b4d6b03 100644 Binary files a/source/images/blueprints/selector-select.png and b/source/images/blueprints/selector-select.png differ diff --git a/source/images/blueprints/selector-target.png b/source/images/blueprints/selector-target.png index ba686317881..a7dcf7d2e2a 100644 Binary files a/source/images/blueprints/selector-target.png and b/source/images/blueprints/selector-target.png differ diff --git a/source/images/blueprints/selector-text.png b/source/images/blueprints/selector-text.png index f0457f9054c..052ce300677 100644 Binary files a/source/images/blueprints/selector-text.png and b/source/images/blueprints/selector-text.png differ diff --git a/source/images/blueprints/selector-theme.png b/source/images/blueprints/selector-theme.png new file mode 100644 index 00000000000..825ea2be8ad Binary files /dev/null and b/source/images/blueprints/selector-theme.png differ diff --git a/source/images/blueprints/selector-time.png b/source/images/blueprints/selector-time.png index 8154e277c48..0e78576abcd 100644 Binary files a/source/images/blueprints/selector-time.png and b/source/images/blueprints/selector-time.png differ