Template

The template integration allows creating entities which derive their values from other data. This is done by specifying templates for properties of an entity, like the name or the state.

Sensors, binary (on/off) sensors, buttons, images, numbers, and selects are covered on this page. They can be configured using UI or YAML file.

For other types, please see the specific pages:

• Alarm control panel
• Cover
• Fan
• Light
• Lock
• Switch
• Vacuum
• Weather

Configuration

To add the Template helper to your Home Assistant instance, use this My button:

YAML configuration

Entities (sensors, binary sensors, buttons, images, numbers, and selections) are defined in your YAML configuration files under the template: key. You can define multiple configuration blocks as a list. Each block defines sensor/binary sensor/number/select entities and can contain an optional update trigger.

For old sensor/binary sensor configuration format, see below.

State-based template binary sensors, buttons, images, numbers, selects and sensors

Template entities will by default update as soon as any of the referenced data in the template updates.

For example, you can have a template that takes the averages of two sensors. Home Assistant will update your template sensor as soon as either source sensor updates.

template:
  - sensor:
      - name: "Average temperature"
        unit_of_measurement: "°C"
        state: >
          {% set bedroom = states('sensor.bedroom_temperature') | float %}
          {% set kitchen = states('sensor.kitchen_temperature') | float %}

          {{ ((bedroom + kitchen) / 2) | round(1, default=0) }}

Trigger-based template binary sensors, buttons, images, numbers, selects and sensors

If you want more control over when an entity updates, you can define a trigger. Triggers follow the same format and work exactly the same as triggers in automations. This feature is a great way to create entities based on webhook data (example), or update entities based on a schedule.

Whenever the trigger fires, all related entities will re-render and it will have access to the trigger data in the templates.

Trigger-based entities do not automatically update when states referenced in the templates change. This functionality can be added back by defining a state trigger for each entity that you want to trigger updates.

The state, including attributes, of trigger-based sensors and binary sensors is restored when Home Assistant is restarted. The state of other trigger-based template entities is not restored.

# Example configuration entry
template:
  - trigger:
      - trigger: time_pattern
        # This will update every night
        hours: 0
        minutes: 0
    sensor:
      # Keep track how many days have past since a date
      - name: "Not smoking"
        state: '{{ ( ( as_timestamp(now()) - as_timestamp(strptime("06.07.2018", "%d.%m.%Y")) ) / 86400 ) | round(default=0) }}'
        unit_of_measurement: "Days"

The above configuration variables describe a configuration section. The template integration allows defining multiple sections.

# Example configuration.yaml entry with two sections
template:
  # Define state-based template entities
  - sensor:
      ...
  - binary_sensor:
      ...

  # Define trigger-based template entities
  - trigger:
      ...
    sensor:
      ...
    binary_sensor:
      ...

Video tutorial

This video tutorial explains how to set up a Trigger based template that makes use of an action to retrieve the weather forecast (precipitation).

Template and action variables

State-based and trigger-based template entities have the special template variable this available in their templates and actions. The this variable is the state object of the entity and aids self-referencing of an entity’s state and attribute in templates and actions. Trigger-based entities also provide the trigger data.

Rate limiting updates

When there are entities present in the template and no triggers are defined, the template will be re-rendered when one of the entities changes states. To avoid this taking up too many resources in Home Assistant, rate limiting will be automatically applied if too many states are observed.

When states is used in a template by itself to iterate all states on the system, the template is re-rendered each time any state changed event happens if any part of the state is accessed. When merely counting states, the template is only re-rendered when a state is added or removed from the system. On busy systems with many entities or hundreds of thousands state changed events per day, templates may re-render more than desirable.

In the below example, re-renders are limited to once per minute because we iterate over all available entities:

template:
  - binary_sensor:
      - name: "Has Unavailable States"
        state: "{{ states | selectattr('state', 'in', ['unavailable', 'unknown', 'none']) | list | count }}"

In the below example, re-renders are limited to once per second because we iterate over all entities in a single domain (sensor):

template:
  - binary_sensor:
      - name: "Has Unavailable States"
        state: "{{ states.sensor | selectattr('state', 'in', ['unavailable', 'unknown', 'none']) | list | count }}"

If the template accesses every state on the system, a rate limit of one update per minute is applied. If the template accesses all states under a specific domain, a rate limit of one update per second is applied. If the template only accesses specific states, receives update events for specifically referenced entities, or the homeassistant.update_entity action is used, no rate limit is applied.

Considerations

Startup

If you are using the state of a platform that might not be available during startup, the Template Sensor may get an unknown state. To avoid this, use the states() function in your template. For example, you should replace {{ states.sensor.moon.state }} with this equivalent that returns the state and never results in unknown: {{ states('sensor.moon') }} .

The same would apply to the is_state() function. You should replace {{ states.switch.source.state == 'on' }} with this equivalent that returns true/false and never gives an unknown result:

{{ is_state('switch.source', 'on') }}

Using blueprints

If you’re just starting out and are not really familiar with templates, we recommend that you start with blueprintA blueprint is a script, automation or template entity configuration with certain parts marked as configurable. This allows users to create multiple scripts, automations or template entities based on the same blueprint, with each having its own configuration-specific settings. [Learn more] template entities. These are template entities which are ready-made by the community and that you only need to configure.

Each blueprint contains the “recipe” for creating a single template entity, but you can create multiple template entities based on the same blueprint.

To create your first template entity based on a blueprint, open up your configuration.yaml file and add:

# Example configuration.yaml template entity based on a blueprint located in config/blueprints/homeassistant/inverted_binary_sensor.yaml
template:
  - use_blueprint:
      path: homeassistant/inverted_binary_sensor.yaml # relative to config/blueprints/template/
      input:
        reference_entity: binary_sensor.foo
    name: Inverted foo
    unique_id: inverted_foo

If you look at the blueprint definition, you will notice it has one input defined (reference_entity), which expects a binary_sensor entity ID. When you create a template entity based on that blueprint, you will have to tell it which of your binary_sensor entities it should use to fill that spot.

Importing blueprints

Home Assistant can import blueprints from the Home Assistant forums, GitHub, and GitHub gists.

1. To import a blueprint, first find a blueprint you want to import.

   • If you just want to practice importing, you can use this URL:

     https://github.com/home-assistant/core/blob/dev/homeassistant/components/template/blueprints/inverted_binary_sensor.yaml
     

2. Download the file and place it under config/blueprints/template/<source or author>/<blueprint name>.yaml

3. Use a config similar to the one above to create a new template entity based on the blueprint you just imported.

4. Make sure to fill in all required inputs.

The blueprint can now be used for creating template entities.

Examples

In this section, you find some real-life examples of how to use template sensors.

Trigger based sensor and binary sensor storing webhook information

Template entities can be triggered using any automation trigger, including webhook triggers. Use a trigger-based template entity to store this information in template entities.

template:
  - trigger:
      - trigger: webhook
        webhook_id: my-super-secret-webhook-id
    sensor:
      - name: "Webhook Temperature"
        state: "{{ trigger.json.temperature }}"
        unit_of_measurement: °C

      - name: "Webhook Humidity"
        state: "{{ trigger.json.humidity }}"
        unit_of_measurement: %

    binary_sensor:
      - name: "Motion"
        state: "{{ trigger.json.motion }}"
        device_class: motion

You can test this trigger entity with the following CURL command:

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"temperature": 5, "humidity": 34, "motion": true}' \
  http://homeassistant.local:8123/api/webhook/my-super-secret-webhook-id

Turning an event into a trigger based binary sensor

You can use a trigger-based template entity to convert any event or other automation trigger into a binary sensor. The below configuration will turn on a binary sensor for 5 seconds when the automation trigger triggers.

template:
  - trigger:
      trigger: event
      event_type: my_event
    binary_sensor:
      - name: Event recently fired
        auto_off: 5
        state: "true"

Using conditions with triggers to control status updates

This example shows how to store the last valid value of a temperature sensor. It will update as long as the source sensor has a valid (numeric) state. Otherwise, the template sensor’s state will remain unchanged.

template:
  - trigger:
      trigger: state
      entity_id: sensor.outside_temperature
    condition:
      - condition: template
        value_template: "{{ is_number(states('sensor.outside_temperature')) }}"
    sensor:
      - name: Outside Temperature last known value
        state: "{{ states('sensor.outside_temperature') }}"

State based sensor exposing sun angle

This example shows the sun angle in the frontend.

template:
  - sensor:
      - name: Sun Angle
        unit_of_measurement: "°"
        state: "{{ '%+.1f'|format(state_attr('sun.sun', 'elevation')) }}"

State based sensor modifying another sensor’s output

If you don’t like the wording of a sensor output, then the Template Sensor can help too. Let’s rename the output of the Sun integration as a simple example:

template:
  - sensor:
      - name: "Sun State"
        state: >
          {% if is_state('sun.sun', 'above_horizon') %}
            up
          {% else %}
            down
          {% endif %}

State based sensor with multiline template with an if test

This example shows a multiple line template with an if test. It looks at a sensing switch and shows on/off in the frontend, and shows ‘standby’ if the power use is less than 1000 watts.

template:
  - sensor:
      - name: "Kettle"
        state: >
          {% if is_state('switch.kettle', 'off') %}
            off
          {% elif state_attr('switch.kettle', 'W')|float < 1000 %}
            standby
          {% elif is_state('switch.kettle', 'on') %}
            on
          {% else %}
            failed
          {% endif %}

State based sensor changing the unit of measurement of another sensor

With a Template Sensor, it’s easy to convert given values into others if the unit of measurement doesn’t fit your needs. Because the sensors do math on the source sensor’s state and need to render to a numeric value, an availability template is used to suppress rendering of the state template if the source sensor does not have a valid numeric state.

template:
  - sensor:
      - name: "Transmission Down Speed"
        unit_of_measurement: "kB/s"
        state: "{{ states('sensor.transmission_down_speed')|float * 1024 }}"
        availability: "{{ is_number(states('sensor.transmission_down_speed')) }}"

      - name: "Transmission Up Speed"
        unit_of_measurement: "kB/s"
        state: "{{ states('sensor.transmission_up_speed')|float * 1024 }}"
        availability: "{{ is_number(states('sensor.transmission_up_speed')) }}"

State based binary sensor - Washing Machine Running

This example creates a washing machine “load running” sensor by monitoring an energy meter connected to the washer. During the washer’s operation, the energy meter will fluctuate wildly, hitting zero frequently even before the load is finished. By utilizing delay_off, we can have this sensor only turn off if there has been no washer activity for 5 minutes.

# Determine when the washing machine has a load running.
template:
  - binary_sensor:
      - name: "Washing Machine"
        delay_off:
          minutes: 5
        state: >
          {{ states('sensor.washing_machine_power')|float > 0 }}

State based binary sensor - Is Anyone Home

This example is determining if anyone is home based on the combination of device tracking and motion sensors. It’s extremely useful if you have kids/baby sitter/grand parents who might still be in your house that aren’t represented by a trackable device in Home Assistant. This is providing a composite of Wi-Fi based device tracking and Z-Wave multisensor presence sensors.

template:
  - binary_sensor:
      - name: People home
        state: >
          {{ is_state('device_tracker.sean', 'home')
             or is_state('device_tracker.susan', 'home')
             or is_state('binary_sensor.office_124', 'on')
             or is_state('binary_sensor.hallway_134', 'on')
             or is_state('binary_sensor.living_room_139', 'on')
             or is_state('binary_sensor.porch_ms6_1_129', 'on')
             or is_state('binary_sensor.family_room_144', 'on') }}

State based binary sensor - device tracker sensor with latitude and longitude attributes

This example shows how to combine a non-GPS (e.g., NMAP) and GPS device tracker while still including latitude and longitude attributes

template:
  - binary_sensor:
      - name: My Device
        state: >
          {{ is_state('device_tracker.my_device_nmap', 'home') or is_state('device_tracker.my_device_gps', 'home') }}
        device_class: "presence"
        attributes:
          latitude: >
            {% if is_state('device_tracker.my_device_nmap', 'home') %}
              {{ state_attr('zone.home', 'latitude') }}
            {% else %}
              {{ state_attr('device_tracker.my_device_gps', 'latitude') }}
            {% endif %}
          longitude: >
            {% if is_state('device_tracker.my_device_nmap', 'home') %}
              {{ state_attr('zone.home', 'longitude') }}
            {% else %}
              {{ state_attr('device_tracker.my_device_gps', 'longitude') }}
            {% endif %}

State based binary sensor - Change the icon when a state changes

This example demonstrates how to use template to change the icon as its state changes. This icon is referencing its own state.

template:
  - binary_sensor:
      - name: Sun Up
        state: >
          {{ is_state("sun.sun", "above_horizon") }}
        icon: >
          {% if is_state("binary_sensor.sun_up", "on") %}
            mdi:weather-sunset-up
          {% else %}
            mdi:weather-sunset-down
          {% endif %}

A more advanced use case could be to set the icon based on the sensor’s own state like above, but when triggered by an event. This example demonstrates a binary sensor that turns on momentarily, such as when a doorbell button is pressed.

The binary sensor turns on and sets the matching icon when the appropriate event is received. After 5 seconds, the binary sensor turns off automatically. To ensure the icon gets updated, there must be a trigger for when the state changes to off.

template:
  - trigger:
      - trigger: event
        event_type: YOUR_EVENT
      - trigger: state
        entity_id: binary_sensor.doorbell_rang
        to: "off"
    binary_sensor:
      name: doorbell_rang
      icon: "{{ (trigger.platform == 'event') | iif('mdi:bell-ring-outline', 'mdi:bell-outline') }}"
      state: "{{ trigger.platform == 'event' }}"
      auto_off:
        seconds: 5

State based select - Control Day/Night mode of a camera

This show how a state based template select can be used to perform an action.

template:
  select:
    - name: "Porch Camera Day-Night Mode"
      unique_id: porch_camera_day_night_mode
      state: "{{ state_attr('camera.porch_camera_sd', 'day_night_mode') }}"
      options: "{{ ['off', 'on', 'auto'] }}"
      select_option:
        - action: tapo_control.set_day_night_mode
          data:
            day_night_mode: "{{ option }}"
          target:
            entity_id: camera.porch_camera_sd

Self referencing

This example demonstrates how the this variable can be used in templates for self-referencing.

template:
  - sensor:
      - name: test
        state: "{{ this.attributes.test | default('Value when missing') }}"
        # not: "{{ state_attr('sensor.test', 'test') }}"
        attributes:
          test: "{{ now() }}"

Trigger based handling of action response data

This example demonstrates how to use an action to call a action with response data and use the response in a template.

template:
  - trigger:
      - trigger: time_pattern
        hours: /1
    action:
      - action: weather.get_forecasts
        data:
          type: hourly
        target:
          entity_id: weather.home
        response_variable: hourly
    sensor:
      - name: Weather Forecast Hourly
        unique_id: weather_forecast_hourly
        state: "{{ now().isoformat() }}"
        attributes:
          forecast: "{{ hourly['weather.home'].forecast }}"

Number entity changing the unit of measurement of another number

This example demonstrates the usage of a template number with a unit of measurement set to change a unit-less value of another number entity.

template:
  - number:
      - name: "Cutting Height"
        unit_of_measurement: "cm"
        unique_id: automower_cutting_height
        state: "{{ states('number.automower_cutting_height_raw')|int(0) * 0.5 + 1.5 }}"
        set_value:
          - service: number.set_value
            target:
              entity_id: number.automower_cutting_height_raw
            data:
              value: "{{ (value - 1.5) * 2 }}"
        step: 0.5
        min: 2
        max: 6
        icon: mdi:ruler

Legacy binary sensor configuration format

This format still works but is no longer recommended. Use modern configuration.

This format is configured as a platform for the binary_sensor integration and not directly under the template integration.

# Example configuration.yaml entry
binary_sensor:
  - platform: template
    sensors:
      sun_up:
        friendly_name: "Sun is up"
        value_template: {{ state_attr('sun.sun', 'elevation') > 0 }}

Legacy Sensor configuration format

This format still works but is no longer recommended. Use modern configuration.

This format is configured as a platform for the sensor integration and not directly under the template integration.

# Example configuration.yaml entry
sensor:
  - platform: template
    sensors:
      solar_angle:
        friendly_name: "Sun angle"
        unit_of_measurement: "degrees"
        value_template: "{{ state_attr('sun.sun', 'elevation') }}"

      sunrise:
        value_template: "{{ state_attr('sun.sun', 'next_rising') }}"

Event event_template_reloaded

Event event_template_reloaded is fired when Template entities have been reloaded and entities thus might have changed.

This event has no additional data.