Text Sensor Component

Text sensors are a lot like normal sensors. But where the “normal” sensors only represent sensors that output numbers, this component can represent any text.

Base Text Sensor Configuration

# Example sensor configuration
name: Livingroom Temperature

# Optional variables:
icon: "mdi:water-percent"

Configuration variables:

  • name (Required, string): The name for the sensor.

    Note

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

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

  • device_class (Optional, string): The device class for the sensor. Only the timestamp and date device classes are supported. Set to "" to remove the default device class of a sensor. Requires Home Assistant 2024.3 or newer.

  • 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 MQTT enabled, All other options from MQTT Component.

Automations:

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

  • on_raw_value (Optional, Automation): An automation to perform when a new value is received that hasn’t passed through any filters. See on_raw_value.

Text Sensor Filters

ESPHome allows you to do some basic pre-processing of text_sensor values before they’re sent to Home Assistant. This is for example useful if you want to manipulate the text_sensor string in some fashion.

There are a lot of filters that sensors support. You define them by adding a filters block in the text_sensor configuration (at the same level as platform; or inside each text_sensor block for platforms with multiple sensors).

Filters are processed in the order they are defined in your configuration.

# Example filters:
filters:
  - to_upper:
  - to_lower:
  - append: "_suffix"
  - prepend: "prefix_"
  - substitute:
    - "suf -> foo"
    - "pre -> bar"
  - lambda: return {"Hello World"};

to_upper

Converts all characters within a string to uppercase (only the English alphabet is supported at this time).

# Example configuration entry
- platform: template
  # ...
  filters:
    - to_upper:

to_lower

Converts all characters within a string to lowercase (only the English alphabet is supported at this time).

# Example configuration entry
- platform: template
  # ...
  filters:
    - to_lower:

append

Adds a string to the end of the current string.

# Example configuration entry
- platform: template
  # ...
  filters:
    - append: "_suffix"

prepend

Adds a string to the start of the current string.

# Example configuration entry
- platform: template
  # ...
  filters:
    - prepend: "prefix_"

substitute

Search the current value of the text sensor for a string, and replace it with another string.

# Example configuration entry
- platform: template
  # ...
  filters:
    - substitute:
      - "suf -> foo"
      - "pre -> bar"

The arguments are a list of substitutions, each in the form TO_FIND -> REPLACEMENT.

map

Lookup the current value of the text sensor in a list, and return the matching item if found. Does not change the value of the text sensor if the current value wasn’t found.

# Example configuration entry
- platform: template
  # ...
  filters:
    - map:
      - high -> On
      - low -> Off

The arguments are a list of substitutions, each in the form LOOKUP -> REPLACEMENT.

lambda

Perform a advanced operations on the text sensor value. The input string is x and the result of the lambda is used as the output (use return).

filters:
  - lambda: |-
      if (x == "Hello") {
        return x + "bar";
      } else {
        return x + "foo";
      }

Text Sensor Automation

You can access the most recent state of the sensor in lambdas using id(sensor_id).state.

on_value

This automation will be triggered when a new value is published. In Lambdas you can get the value from the trigger with x.

text_sensor:
  - platform: version
    # ...
    on_value:
      then:
        - lambda: |-
            ESP_LOGD("main", "The current version is %s", x.c_str());

Configuration variables: See Automation.

on_raw_value

This automation will be triggered when a new value is received that hasn’t passed through any filters. In Lambdas you can get the value from the trigger with x.

text_sensor:
  - platform: version
    # ...
    on_raw_value:
      then:
        - lambda: |-
            ESP_LOGD("main", "The current version is %s", x.c_str());

Configuration variables: See Automation.

text_sensor.state Condition

This Condition allows you to check if a given text sensor has a specific state.

on_...:
  - if:
      condition:
        # Checks if "my_text_sensor" has state "Hello World"
        text_sensor.state:
          id: my_text_sensor
          state: 'Hello World'

Configuration variables:

  • id (Required, ID): The text sensor ID.

  • state (Required, templatable, string): The state to compare to.

Note

This condition can also be expressed in lambdas:

if (id(my_text_sensor).state == "Hello World") {
  // do something
}

lambda calls

From lambdas, you can call several methods on all text sensors to do some advanced stuff (see the full API Reference for more info).

  • publish_state(): Manually cause the sensor to push out a value.

    // Within lambda, push a value of "Hello World"
id(my_sensor).publish_state("Hello World");

  • .state: Retrieve the current value of the sensor as an std::string object.

    // For example, create a custom log message when a value is received:
std::string val = id(my_sensor).state;
ESP_LOGI("main", "Value of my sensor: %s", val.c_str());

See Also