Select Component

ESPHome has support for components to create a select entity. A select entity is basically an option list that can be set by either yaml, hardware or the user/frontend.

NOTE

Home Assistant Core 2021.8 or higher is required for ESPHome select entities to work.

Base Select Configuration

All selects in ESPHome have a name and an optional icon.

# Example select configuration
name: Livingroom Mood
id: my_select

# Optional variables:
icon: "mdi:emoticon-outline"

Configuration variables:

• id (Optional, string): Manually specify the ID for code generation. At least one of id and name must be specified.
• name (Optional, string): The name for the select. At least one of id and name must be specified.

NOTE

If you have a friendly_name set for your device and you want the select to use that name, you can set name: None.

• icon (Optional, icon): Manually set the icon to use for the select in the frontend.

• internal (Optional, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an id without a name will implicitly set this to true.

• disabled_by_default (Optional, boolean): If true, then this entity should not be added to any client’s frontend, (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to false.

• entity_category (Optional, string): The category of the entity. See https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. Set to "" to remove the default entity category.

• If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See Webserver Version 3.

• on_value (Optional, Automation): An automation to perform when a new value is published. See on_value.

MQTT Options:

• All other options from MQTT Component.

Accessing the current option

You can access the most recent state of the select in lambdas using id(select_id).current_option(). For more information on using lambdas with select, see lambda calls.

Triggers

on_value

This automation will be triggered whenever a value is set/published, even if the value is the same as before. In Lambdas you can get the value from the trigger with x and the index offset of the selected value with i.

select:
  - platform: template
    # ...
    on_value:
      then:
        - logger.log:
            format: "Chosen option: %s (index %d)"
            args: ["x.c_str()", "i"]

Configuration variables: See Automation.

Conditions

select.is Condition

This Condition checks if the select is set to any one of a list of options. A lambda may also be used for more complex computations.

Configuration variables:

• id (Required, ID): The ID of the select to test.
• options (Optional, list): A string, or list of strings to compare with the current selection. The condition is true if any match.
• lambda (Optional, templatable): A lambda returning a boolean value. The current selection is passed in a StringRef argument called current.

Only one of options and lambda must be provided.

# In some trigger:
on_...:
  - if:
      condition:
        select.is:
          id: my_select
          options: [Happy, Ecstatic]
      then:
        - logger.log: "Select is Happy or Ecstatic"
  - if:
      condition:
        select.is:
          id: my_select
          options: "Happy" # Single option
      then:
        - logger.log: "Select is exactly Happy"
  - if:
      condition:
        select.is:
          id: my_select
          lambda: return id(text_sensor).state == current || "Happy" == current;
      then:
        - logger.log: "Select is Happy, or matches some variable state"

Actions

select.set Action

This is an Action for setting the active option using an option value.

- select.set:
    id: my_select
    option: "Happy"

Configuration variables:

• id (Required, ID): The ID of the select to set.
• option (Required, string, templatable): The option to set the select to.

When a non-existing option value is used, a warning is logged and the state of the select is left as-is.

select.set_index Action

This is an Action for setting the active option using its index offset.

- select.set_index:
    id: my_select
    index: 3

Configuration variables:

• id (Required, ID): The ID of the select to set.
• index (Required, int, templatable): The index offset of the option to be activated.

When a non-existing index value is used, a warning is logged and the state of the select is left as-is.

select.next Action

This is an Action for selecting the next option in a select component.

- select.next:
    id: my_select
    cycle: false

# Shorthand
- select.next: my_select

Configuration variables:

• id (Required, ID): The ID of the select to set.
• cycle (Optional, boolean): Whether or not to jump back to the first option of the select when the last option is currently selected. Defaults to true.

select.previous Action

This is an Action for selecting the previous option in a select component.

- select.previous:
    id: my_select
    cycle: true

# Shorthand
- select.previous: my_select

Configuration variables:

• id (Required, ID): The ID of the select to set.
• cycle (Optional, boolean): Whether or not to jump to the last option of the select when the first option is currently selected. Defaults to true.

select.first Action

This is an Action for selecting the first option in a select component.

- select.first:
    id: my_select

# Shorthand
- select.first: my_select

Configuration variables:

• id (Required, ID): The ID of the select to set.

select.last Action

This is an Action for selecting the last option in a select component.

- select.last:
    id: my_select

# Shorthand
- select.last: my_select

Configuration variables:

• id (Required, ID): The ID of the select to set.

select.operation Action

This is an Action that can be used to change the active option in a select component (first, last, previous or next), using a generic templatable action call.

# Using values
- select.operation:
    id: my_select
    operation: Next
    cycle: true

# Or templated (lambdas)
- select.operation:
    id: my_select
    operation: !lambda "return SELECT_OP_NEXT;"
    cycle: !lambda "return true;"

Configuration variables:

• id (Required, ID): The ID of the select to set.

• operation (Required, string, templatable): The operation to perform. One of FIRST, LAST, PREVIOUS or NEXT (case insensitive). When writing a lambda for this field, then return one of the following enum values: SELECT_OP_FIRST, SELECT_OP_LAST, SELECT_OP_PREVIOUS or SELECT_OP_NEXT.

• cycle (Optional, bool, templatable): Can be used for options NEXT and PREVIOUS to specify whether or not to wrap around the options list when respectively the last or first option in the select is currently active.

Using Selects in Lambdas

From lambdas, you can call several methods on selects (see the full API Reference for more info).

• .make_call() : Create a call for changing the select state.

    // Within lambda, select the "Happy" option.
    auto call = id(my_select).make_call();
    call.set_option("Happy");
    call.perform();

Check the API reference for information on the methods that are available for the SelectCall object. You can for example also use call.select_first() to select the first option or call.select_next(true) to select the next option with the cycle feature enabled.

• .current_option() : Retrieve the currently selected option of the select. Returns StringRef.

    // For example, create a custom log message when an option is selected:
    auto option = id(my_select).current_option();
    ESP_LOGI("main", "Option of my select: %.*s", (int) option.size(), option.c_str());

    # Check if a specific option is selected (direct string comparison in a lambda condition)
    - if:
        condition:
          - lambda: 'return id(my_select).current_option() == "my_option_value";'

• .size() : Retrieve the number of options in the select.

    auto size = id(my_select).size();
    ESP_LOGI("main", "Select has %d options", size);

• .index_of(<option value>) : Retrieve the index offset for an option value.

    auto index = id(my_select).index_of("Happy");
    if (index.has_value()) {
      ESP_LOGI("main", "'Happy' is at index: %d", index.value());
    } else {
      ESP_LOGE("main", "There is no option 'Happy'");
    }

• .active_index() : Retrieve the index of the currently active option.

    auto index = id(my_select).active_index();
    if (index.has_value()) {
      ESP_LOGI("main", "Option at index %d is active", index.value());
    } else {
      ESP_LOGI("main", "No option is active");
    }

• .at(<index offset>) : Retrieve the option value at a given index offset.

    auto index = 1;
    auto option = id(my_select).at(index);
    if (option.has_value()) {
      auto value = option.value();
      ESP_LOGI("main", "Option at %d is: %s", index, value);
    } else {
      ESP_LOGE("main", "Index %d does not exist", index);
    }

• .has_option(<option value>) : Check if the select contains the given option value.

    auto option = "Happy";
    if (id(my_select).has_option(option)) {
      ESP_LOGI("main", "Select has option '%s'", option);
    }

• .has_index(<index offset>) : Check if the select contains an option value for the given index offset.

    auto index = 3;
    if (id(my_select).has_index(index)) {
      ESP_LOGI("main", "Select has index offset %d", index);
    }

Example

Setting up three options and set component state to selected option value.

select:
  - platform: template
    name: Mode
    id: mode
    options:
     - "Option1"
     - "Option2"
     - "Option3"
    initial_option: "Option1"
    optimistic: true
    set_action:
      - logger.log:
          format: "Chosen option: %s"
          args: ["x.c_str()"]

See Also

• API Reference: Select
• API Reference: SelectCall