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.
There is currently support for the following device types within Home Assistant:
- Alarm control panel
- Binary sensor
- Button
- Cover
- Fan
- Image
- Light
- Lock
- Number
- Select
- Sensor
- Switch
- Vacuum
- Weather
Configuration
To add the Template helper to your Home Assistant instance, use this My button:
Manual configuration steps
If the above My button doesn’t work, you can also perform the following steps manually:
-
Browse to your Home Assistant instance.
-
At the top of the screen, select the tab: Helpers.
-
In the bottom right corner, select the
Create helper button. -
From the list, select Template.
-
Follow the instructions on screen to complete the setup.
To be able to add Helpers via the user interface, you should have default_config:
in your configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]. It should already be there by default unless you removed it.
Configuration using our user interface provides a more limited subset of options, making this integration more accessible while covering most use cases.
If you need more specific features for your use case, the manual YAML-configuration section of this integration might provide them.
YAML configuration
Entities 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 optional update triggers.
State-based template entities
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.
Trigger-based template binary sensors, images, lights, numbers, selects, sensors, switches, and weathers
If you want more control over when an entity updates, you can define triggers. 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 a 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.
Buttons do not support using trigger
or action
options.
Configuration reference
Configuration Variables
Define actions to be executed when the trigger fires (for trigger-based entities only). Optional. Variables set by the action script are available when evaluating entity templates. This can be used to interact with anything using actions, in particular actions with response data. See action documentation.
Define conditions that have to be met after a trigger fires and before any actions are executed or sensor updates are performed (for trigger-based entities only). Optional. See condition documentation.
Define one or multiple automation triggers to update the entities. Optional. If omitted will update based on referenced entities. See trigger documentation.
The unique ID for this config block. This will be prefixed to all unique IDs of all entities in this block.
Key-value pairs of variable definitions which can be referenced and used in the templates below (for trigger-based entities only). Mostly used by blueprints. With State-based template entities, variables are only resolved when the configuration is loaded or reloaded. Trigger based template entities resolve variables between triggers and actions.
Common Device Configuration Options
Each entity platform has its own set of configuration options, but there are some common options that can be used across all entity platforms.
Configuration Variables
Defines a template to get the available
state of the entity. If the template either fails to render or returns True
, "1"
, "true"
, "yes"
, "on"
, "enable"
, or a non-zero number, the entity will be available
. If the template returns any other value, the entity will be unavailable
. If not configured, the entity will always be available
. Note that the string comparison is not case sensitive; "TrUe"
and "yEs"
are allowed.
Defines a template for the icon of the entity.
Defines a template for the entity picture of the sensor.
Defines a template to get the name of the entity.
Alarm Control Panel
The template alarm control panel platform allows you to create a alarm control panels with templates to define the state and scripts to define each actions.
Alarm control panel entities can be created from the frontend in the Helpers section or via YAML. Alarm control panel entities do not support trigger-based configurations.
Configuration Variables
List of alarm control panels
Defines an action to run when the alarm is armed to away mode.
Defines an action to run when the alarm is armed to custom bypass mode.
Defines an action to run when the alarm is armed to home mode.
Defines an action to run when the alarm is armed to night mode.
Defines an action to run when the alarm is armed to vacation mode.
One of number
, text
or no_code
. Format for the code used to arm/disarm the alarm.
Defines an action to run when the alarm is disarmed.
Defines a template to set the state of the alarm panel. Only the states armed_away
, armed_home
, armed_night
, armed_vacation
, arming
, disarmed
, pending
, triggered
and unavailable
are used.
Defines an action to run when the alarm is triggered.
Binary Sensor
The template binary sensor platform allows you to create binary sensors with templates to define the state and attributes.
Binary sensor entities can be created from the frontend in the Helpers section or via YAML.
Configuration Variables
List of binary sensors
Defines templates for attributes of the entity.
The attribute and corresponding template.
Requires a trigger. After how much time the entity should turn off after it rendered ‘on’.
The amount of time the template state must be not met before this sensor will switch to off
. This can also be a template.
The amount of time (e.g. 0:00:05
) the template state must be met before this sensor will switch to on
. This can also be a template.
Sets the class of the device, changing the device state and icon that is displayed on the UI (see below). It does not set the unit_of_measurement
.
The sensor is on
if the template evaluates as True
, yes
, on
, enable
or a positive number. Any other value will render it as off
. The actual appearance in the frontend (Open
/Closed
, Detected
/Clear
etc) depends on the sensor’s device_class value
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.
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.
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
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.
Trigger based binary sensor - Change state and icon when a custom event is received
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.
Button
The template button platform allows you to create button entities with scripts to define each action.
Button entities can be created from the frontend in the Helpers section or via YAML.
Cover
The template cover platform allows you to create covers with templates to define the state and scripts to define each action.
Cover entities can only be created from YAML.
Configuration Variables
Characteristics of a cover
Defines an action to close the cover.
Sets the class of the device, changing the device state and icon that is displayed on the frontend.
Defines an action to open the cover. If open_cover
is specified, close_cover
must also be specified. At least one of open_cover
and set_cover_position
must be specified.
Force cover position to use optimistic mode.
Defines a template to get the position of the cover. Legal values are numbers between 0
(closed) and 100
(open). If the template produces a None
value the current position will be set to unknown
.
Defines an action to set to a cover position (between 0
and 100
). The variable position
will contain the entity’s set position.
Defines an action to set the tilt of a cover (between 0
and 100
). The variable tilt
will contain the entity’s set tilt position.
Defines a template to get the state of the cover. Valid output values from the template are open
, opening
, closing
and closed
which are directly mapped to the corresponding states. In addition, true
is valid as a synonym to open
and false
as a synonym to closed
. If both a state
and a position
template are specified, only opening
and closing
are set from the state
template. If the template produces a None
value the state will be set to unknown
.
Defines an action to stop the cover.
Defines a template to get the tilt state of the cover. Legal values are numbers between 0
(closed) and 100
(open). If the template produces a None
value, the current tilt state will be set to unknown
.
Force cover tilt position to use optimistic mode.
Cover Optimistic Mode
In optimistic mode, the cover position state is maintained internally. This mode is automatically enabled if neither state
or position
are specified. Note that this is unlikely to be very reliable without some feedback mechanism, since there is otherwise no way to know if the cover is moving properly. The cover can be forced into optimistic mode by using the optimistic
attribute. There is an equivalent mode for tilt_position
that is enabled when tilt
is not specified or when the tilt_optimistic
attribute is used.
Combining state and position templates
If both a state
and a position
are specified only opening
and closing
states are set directly from the state
, the open
and closed
states will instead be derived from the cover position.
value_template output | result |
---|---|
open | state defined by position_template
|
closed | state defined by position_template
|
true | state defined by position_template
|
false | state defined by position_template
|
opening | state set to opening
|
closing | state set to closing
|
No change of state or position |
State based cover - Garage Door
This example converts a garage door with a controllable switch and position sensor into a cover. The condition check is optional, but suggested if you use the same switch to open and close the garage.
State based cover - Optimistic Garage Door with Momentary Switch
This example converts a garage door with a momentary switch.
Fan
The template fan platform allows you to create fans with templates to define the state and scripts to define each action.
Fan entities can only be created from YAML. Fan entities do not support trigger-based configurations.
Configuration Variables
List of fans
Defines a template to get the osc state of the fan. Valid values: true
, false
.
Defines a template to get the direction of the fan. Valid values: forward
, reverse
.
Defines a template to get the speed percentage of the fan.
Defines a template to get the preset mode of the fan.
List of preset modes the fan is capable of. This is an arbitrary list of strings and must not contain any speeds.
Defines an action to run when the fan is given a speed percentage command.
Defines an action to run when the fan is given a preset command.
Defines an action to run when the fan is given an oscillation state command.
Defines an action to run when the fan is given a direction command.
The number of speeds the fan supports. Used to calculate the percentage step for the fan.increase_speed
and fan.decrease_speed
actions.
Defines a template to get the state of the fan. Valid values: on
, off
.
Defines an action to run when the fan is turned on.
Defines an action to run when the fan is turned off.
Converting from speeds to percentage
When converting a fan with 3 speeds from the old fan entity model, the following percentages can be used:
0 - off
33 - low
66 - medium
100 - high
State based fan - Helper fan
This example uses an input_boolean and an input_number to mimic a fan, and the example shows multiple actions for set_percentage
.
State based fan - Fan with preset modes
This example uses an existing fan with only a percentage. It extends the percentage value into useable preset modes without a helper entity.
Image
The template image platform allows you to create image entities with templates to define the image URL.
Image entities can be created from the frontend in the Helpers section or via YAML.
Light
The template light platform allows you to create lights with templates to define the state and scripts to define each action.
Light entities can only be created from YAML.
Configuration Variables
List of your lights.
Defines a template to get the effect of the light.
Defines a template to get the list of supported effects. Must render a list.
Defines a template to get the HS color of the light. Must render a tuple (hue, saturation).
Defines a template to get the brightness of the light.
Defines a template to get the minimum mired value of the light.
Defines a template to get the maximum mired value of the light.
Defines a template to get the RGB color of the light. Must render a tuple or a list (red, green, blue).
Defines a template to get the RGBW color of the light. Must render a tuple or a list (red, green, blue, white).
Defines a template to get the RGBWW color of the light. Must render a tuple or a list (red, green, blue, cold white, warm white).
Defines an action to run when the light is given an effect command. Receives the variable effect
. May also receive the variables brightness
, and/or transition
.
Defines an action to run when the light is given a brightness command. The script will only be called if the turn_on
call only ha brightness, and optionally transition. Receives variables brightness
and, optionally, transition
.
Defines an action to run when the light is given a color temperature command. Receives variable color_temp
. May also receive variables brightness
and/or transition
.
Defines an action to run when the light is given a hs color command. Available variables: hs
as a tuple, h
and s
Defines an action to run when the light is given an RGB color command. Available variables: rgb
as a tuple, r
, g
and b
.
Defines an action to run when the light is given an RGBW color command. Available variables: rgbw
as a tuple, rgb
as a tuple, r
, g
, b
and w
.
Defines an action to run when the light is given an RGBWW color command. Available variables: rgbww
as a tuple, rgb
as a tuple, r
, g
b
, cw
and ww
.
Defines a template to set the state of the light. If not defined, the switch will optimistically assume all commands are successful.
Defines a template to get if the light supports transition. Should return a boolean value (True/False). If this value is True
, the transition parameter in a turn on
or turn off
call will be passed as a named parameter transition
in either of the scripts.
Defines a template to get the color temperature of the light.
Defines an action to run when the light is turned on. May receive the variables brightness
and/or transition
.
Defines an action to run when the light is turned off. May receive the variable transition
.
Light Considerations
Transition doesn’t have its own script, it will instead be passed as a named parameter transition
to the turn_on
, turn_off
, brightness
, color_temp
, effect
, hs_color
, rgb_color
, rgbw_color
or rgbww_color
scripts. Brightness will be passed as a named parameter brightness
to either of turn_on
, color_temp
, effect
, hs_color
, rgb_color
, rgbw_color
or rgbww_color
scripts if the corresponding parameter is also in the call. In this case, the brightness script (set_level
) will not be called. If only brightness is passed to light.turn_on
action, then set_level
script is called.
State based light - Theater Volume Control
This example shows a light that is actually a home theater’s volume. This
integration gives you the flexibility to provide whatever you’d like to send as
the payload to the consumer including any scale conversions you may need to
make; the media player integration needs a floating
point percentage value from 0.0
to 1.0
.
State based light - Make a global light entity for a multi-segment WLED light
This example shows how to group together 2 RGBW segments from the same WLED controller into a single usable light.
Lock
The template lock platform allows you to create locks with templates to define the state and scripts to define each action.
Lock entities can only be created from YAML. Lock entities do not support trigger-based configurations.
Configuration Variables
List of locks
Defines a template to get the code_format
attribute of the entity. This template must evaluate to a valid Python regular expressionNone
. If it evaluates to a not-None
value, you are prompted to enter a code when interacting with the lock. The code will be matched against the regular expression, and the lock/unlock actions will be executed only if they match. The actual validity of the entered code must be verified within these actions. If there’s a syntax error in the template, the entity will be unavailable. If the template fails to render for other reasons or if the regular expression is invalid, no code will be accepted, and the lock/unlock actions will never be invoked.
Defines an action to run when the lock is locked.
Defines an action to run when the lock is opened.
Flag that defines if the lock works in optimistic mode.
Defines a template to set the state of the lock.
Defines an action to run when the lock is unlocked.
State based lock - Lock from a switch
This example shows a lock that copies data from a switch.
State based lock - Optimistic mode
This example shows a lock in optimistic mode. This lock will immediately change state after command and will not wait for state update from the sensor.
State based lock - Sensor and Two Switches
This example shows a lock that takes its state from a sensor, and uses two momentary switches to control a device.
State based lock - Secret code
This example shows a lock that copies data from a switch. It needs a PIN code defined as a secret to unlock and no code to lock. Note that the actual validity check of the code is part of the unlock
action and should always happen there or in scripts called from these actions. In this way, you can not only perform code checks against static values, but also dynamic ones (for instance, TOTPs).
In secrets.yaml
:
Number
The template number platform allows you to create number entities with templates to define the state and scripts to define each action.
Number entities can be created from the frontend in the Helpers section or via YAML.
Configuration Variables
List of numbers
Template for the number’s maximum value.
Template for the number’s minimum value.
Flag that defines if number works in optimistic mode. When enabled, the number’s state will update immediately when changed through the UI or service calls, without waiting for the template defined in state
to update. When disabled (default), the number will only update when the state
template returns a new value.
Defines actions to run when the number value changes. The variable value
will contain the number entered.
Template for the number’s current value.
Defines the units of measurement of the number, if any.
Template for the number’s increment/decrement step.
State based number - 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.
Select
The template select platform allows you to create select entities with templates to define the state and scripts to define each action.
Select entities can be created from the frontend in the Helpers section or via YAML.
Configuration Variables
List of selects
Flag that defines if select works in optimistic mode. When enabled, the select’s state will update immediately when a new option is chosen through the UI or service calls, without waiting for the template defined in state
to update. When disabled (default), the select will only update when the state
template returns a new value.
Template for the select’s available options.
Defines actions to run to select an option from the options
list. The variable option
will contain the option selected.
Template for the select’s current value.
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.
Sensor
The template sensor platform allows you to create sensors with templates to define the state and attributes.
Sensor entities can be created from the frontend in the Helpers section or via YAML.
Configuration Variables
List of sensors
Defines templates for attributes of the entity.
The attribute and corresponding template.
Defines a template that describes when the state of the sensor was last reset. Must render to a valid datetime
. Only available when state_class
is set to total
Defines a template to get the state of the sensor. If the sensor is numeric, i.e. it has a state_class
or a unit_of_measurement
, the state template must render to a number or to none
. The state template must not render to a string, including unknown
or unavailable
. An availability
template may be defined to suppress rendering of the state template.
The state_class of the sensor. This will also display the value based on the user profile Number Format setting and influence the graphical presentation in the history visualization as a continuous value. If you desire to include the sensor in long-term statistics, include this key and assign it the appropriate value
State based sensor - Exposing sun angle
This example shows the sun angle in the frontend.
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:
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.
Trigger based sensor - Using conditions to control 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.
Switch
The template switch platform allows you to create switches with templates to define the state and scripts to define each action.
Switch entities can be created from the frontend in the Helpers section or via YAML.
Configuration Variables
List of switches
Defines a template to set the state of the switch. If not defined, the switch will optimistically assume all commands are successful.
Defines an action or list of actions to run when the switch is turned off.
Defines an action or list of actions to run when the switch is turned on.
State based switch - Invert a Switch
This example shows a switch that is the inverse of another switch.
State based switch - Toggle Switch
This example shows a switch that takes its state from a sensor and toggles a switch.
State based switch - Sensor and Two Switches
This example shows a switch that takes its state from a sensor, and uses two momentary switches to control a device.
State based switch - Optimistic Switch
This example switch with an assumed state based on the actions performed. This switch will immediately change state after a turn_on
/turn_off
command.
Vacuum
The template vacuum platform allows you to create vacuum entities with templates to define the state and scripts to define each action.
Vacuum entities can only be created via YAML. Vacuum entities do not support trigger-based configurations.
Configuration Variables
List of vacuum entities
Defines templates for attributes of the entity.
The attribute and corresponding template.
Defines a template to get the battery level of the vacuum. Legal values are numbers between 0
and 100
.
Defines an action to run when the vacuum is given a clean spot command.
Defines a template to get the fan speed of the vacuum.
Defines an action to run when the vacuum is given a locate command.
Defines an action to run when the vacuum is paused.
Defines an action to run when the vacuum is given a return to base command.
Defines an action to run when the vacuum is given a command to set the fan speed.
Defines an action to run when the vacuum is started.
Defines a template to get the state of the vacuum. Valid value: docked
/cleaning
/idle
/paused
/returning
/error
Defines an action to run when the vacuum is stopped.
State based vacuum - Control vacuum with Harmony Hub
This example shows how you can use a Template Vacuum to control an IR vacuum cleaner using the Harmony Hub Remote integration.
State based vacuum - Custom attributes
This example shows how to add custom attributes.
Weather
The template weather platform allows you to create weather entities with templates to define the state and attributes.
Weather entities can only be created via YAML.
Configuration Variables
List of weather entities
The current apparent (feels-like) temperature.
The current cloud coverage.
The current weather condition.
The current dew point.
Daily forecast data.
Hourly forecast data.
Twice daily forecast data.
The current humidity.
The current ozone level.
Unit for precipitation output. Valid options are km, mi, ft, m, cm, mm, in, yd.
The current air pressure.
Unit for pressure_template output. Valid options are Pa, hPa, kPa, bar, cbar, mbar, mmHg, inHg, psi.
The current temperature.
Unit for temperature_template output. Valid options are °C, °F, and K.
The current visibility.
Unit for visibility_template output. Valid options are km, mi, ft, m, cm, mm, in, yd.
The current wind gust speed.
The current wind speed.
Unit for wind_speed_template output. Valid options are m/s, km/h, mph, mm/d, in/d, and in/h.
The current wind bearing.
Trigger based weather - Weather Forecast from response data
This example demonstrates how to use an action
to call a action with response data
and use the response in a template.
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).
Combining multiple template entities
The template integration allows defining multiple sections.
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.
You can test this trigger entity with the following CURL command:
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 current state object of the entity and aids self-referencing of an entity’s state and attributes in templates and actions. Trigger-based entities also provide the trigger data.
Self-referencing using this
provides the state and attributes for the entity before rendering the templates to calculate a new state. In other words, it contains the previous state.
Self referencing
This example demonstrates how the this
variable can be used in templates for self-referencing.
Optimistic mode
For template entities that support interactivity (like number
and select
), you can enable optimistic mode by setting the optimistic
parameter to true
. This affects how the entity’s state updates when you interact with it:
-
With optimistic mode disabled (default): When you interact with the entity (for example, selecting a new option in a dropdown or setting a new number value), the entity’s state in Home Assistant will only update after the underlying template defined in the
state
parameter returns the new value. -
With optimistic mode enabled: When you interact with the entity, the entity’s state in Home Assistant immediately updates to reflect your change, without waiting for the
state
template to update. This provides a more responsive UI experience but may not reflect the actual state if the underlying action fails or takes time to complete.
Optimistic mode is particularly useful when:
- The underlying system doesn’t provide immediate feedback
- You want a more responsive UI experience
- You’re confident the action will succeed
When optimistic mode is disabled (default), you get more accuracy but potentially a less responsive UI, as the entity only updates after confirmation from the underlying system.
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.
Define a trigger to avoid a rate limit and get more control over entity updates.
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:
In the below example, re-renders are limited to once per second because we iterate over all entities in a single domain (sensor):
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:
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. Blueprints are shared by the community on the blueprints exchange in the forum. [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:
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.
-
To import a blueprint, first find a blueprint you want to import.
-
If you just want to practice importing, you can use this URL:
-
-
Download the file and place it under
config/blueprints/template/<source or author>/<blueprint name>.yaml
-
Use a config similar to the one above to create a new template entity based on the blueprint you just imported.
-
Make sure to fill in all required inputs.
The blueprint can now be used for creating template entities.
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.
Legacy Alarm Control Panel configuration format
These formats still work but are no longer recommended. Use modern configuration.
This format is configured as a platform for the alarm_control_panel
integration and not directly under the template
integration.
Configuration Variables
List of your panels.
The slug of the panel.
An ID that uniquely identifies this alarm control panel. Set this to a unique value to allow customization through the UI.
Defines a template to set the state of the alarm panel. Only the states armed_away
, armed_home
, armed_night
, armed_vacation
, arming
, disarmed
, pending
, triggered
and unavailable
are used.
Defines an action to run when the alarm is disarmed.
Defines an action to run when the alarm is armed to away mode.
Defines an action to run when the alarm is armed to home mode.
Defines an action to run when the alarm is armed to night mode.
Defines an action to run when the alarm is armed to vacation mode.
Defines an action to run when the alarm is armed to custom bypass mode.
Defines an action to run when the alarm is triggered.
Legacy Binary Sensor configuration format
These formats still work but are 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.
Configuration Variables
List of your sensors.
The slug of the sensor.
An ID that uniquely identifies this binary sensor. Set this to a unique value to allow customization through the UI.
Sets the class of the device, changing the device state and icon that is displayed on the frontend.
The sensor is on
if the template evaluates as True
and off
otherwise. The actual appearance in the frontend (Open
/Closed
, Detected
/Clear
etc) depends on the sensor’s device_class value
Defines a template to get the available
state of the entity. If the template either fails to render or returns True
, "1"
, "true"
, "yes"
, "on"
, "enable"
, or a non-zero number, the entity will be available
. If the template returns any other value, the entity will be unavailable
. If not configured, the entity will always be available
. Note that the string comparison not case sensitive; "TrUe"
and "yEs"
are allowed.
Defines a template for the icon of the sensor.
Defines a template for the entity picture of the sensor.
Defines templates for attributes of the sensor.
The attribute and corresponding template.
The amount of time the template state must be met before this sensor will switch to on
. This can also be a template.
Legacy Cover configuration format
This format still works but is no longer recommended. Use modern configuration.
This format is configured as a platform for the cover
integration and not directly under the template
integration.
Configuration Variables
List of your covers.
An ID that uniquely identifies this cover. Set this to a unique value to allow customization through the UI.
Defines a template to get the state of the cover. Valid output values from the template are open
, opening
, closing
and closed
which are directly mapped to the corresponding states. In addition, true
is valid as a synonym to open
and false
as a synonym to closed
. If both a value_template
and a position_template
are specified, only opening
and closing
are set from the value_template
. If the template produces a None
value the state will be set to unknown
.
Defines a template to get the position of the cover. Legal values are numbers between 0
(closed) and 100
(open). If the template produces a None
value the current position will be set to unknown
.
Defines a template to specify which icon to use.
Defines a template for the entity picture of the cover.
Defines a template to get the available
state of the entity. If the template either fails to render or returns True
, "1"
, "true"
, "yes"
, "on"
, "enable"
, or a non-zero number, the entity will be available
. If the template returns any other value, the entity will be unavailable
. If not configured, the entity will always be available
. Note that the string comparison is not case sensitive; "TrUe"
and "yEs"
are allowed.
Sets the class of the device, changing the device state and icon that is displayed on the frontend.
Defines an action to open the cover. If open_cover
is specified, close_cover
must also be specified. At least one of open_cover
and set_cover_position
must be specified.
Defines an action to close the cover.
Defines an action to stop the cover.
Defines an action to set to a cover position (between 0
and 100
). The variable position
will contain the entity’s set position.
Defines an action to set the tilt of a cover (between 0
and 100
). The variable tilt
will contain the entity’s set tilt position.
Force cover position to use optimistic mode.
Force cover tilt position to use optimistic mode.
Defines a template to get the tilt state of the cover. Legal values are numbers between 0
(closed) and 100
(open). If the template produces a None
value the current tilt state will be set to unknown
.
Legacy Fan configuration format
This format still works but is no longer recommended. Use modern configuration.
This format is configured as a platform for the fan
integration and not directly under the template
integration.
Configuration Variables
List of your fans.
An ID that uniquely identifies this fan. Set this to a unique value to allow customization through the UI.
Defines a template to get the state of the fan. Valid values: on
, off
Defines a template to get the speed percentage of the fan.
Defines a template to get the preset mode of the fan.
Defines a template to get the osc state of the fan. Valid values: true
, false
Defines a template to get the direction of the fan. Valid values: forward
, reverse
Defines a template to get the available
state of the entity. If the template either fails to render or returns True
, "1"
, "true"
, "yes"
, "on"
, "enable"
, or a non-zero number, the entity will be available
. If the template returns any other value, the entity will be unavailable
. If not configured, the entity will always be available
. Note that the string comparison not case sensitive; "TrUe"
and "yEs"
are allowed.
Defines an action to run when the fan is turned on.
Defines an action to run when the fan is turned off.
Defines an action to run when the fan is given a speed percentage command.
Defines an action to run when the fan is given a preset command.
Defines an action to run when the fan is given an osc state command.
Defines an action to run when the fan is given a direction command.
List of preset modes the fan is capable of. This is an arbitrary list of strings and must not contain any speeds.
Legacy Light configuration format
This format still works but is no longer recommended. Use modern configuration.
This format is configured as a platform for the light
integration and not directly under the template
integration.
Configuration Variables
List of your lights.
An ID that uniquely identifies this light. Set this to a unique value to allow customization through the UI.
Defines a template to get the state of the light.
Defines a template to get the brightness of the light.
Defines a template to get the color temperature of the light.
Defines a template to get the HS color of the light. Must render a tuple (hue, saturation).
Defines a template to get the RGB color of the light. Must render a tuple or a list (red, green, blue).
Defines a template to get the RGBW color of the light. Must render a tuple or a list (red, green, blue, white).
Defines a template to get the RGBWW color of the light. Must render a tuple or a list (red, green, blue, cold white, warm white).
Defines a template to get if light supports transition. Should return boolean value (True/False). If this value is True
transition parameter in a turn on or turn off call will be passed as a named parameter transition
to either of the scripts.
Defines a template to get the list of supported effects. Must render a list
Defines a template to get the effect of the light.
Defines a template to get the min mireds value of the light.
Defines a template to get the max mireds value of the light.
Defines a template for an icon or picture, e.g., showing a different icon for different states.
Defines a template to get the available
state of the entity. If the template either fails to render or returns True
, "1"
, "true"
, "yes"
, "on"
, "enable"
, or a non-zero number, the entity will be available
. If the template returns any other value, the entity will be unavailable
. If not configured, the entity will always be available
. Note that the string comparison not case sensitive; "TrUe"
and "yEs"
are allowed.
Defines an action to run when the light is turned on. May receive variables brightness
and/or transition
.
Defines an action to run when the light is turned off. May receive variable transition
.
Defines an action to run when the light is given a brightness command. The script will only be called if the turn_on
call only has brightness, and optionally transition. Receives variables brightness
and optionally transition
.
Defines an action to run when the light is given a color temperature command. Receives variable color_temp
. May also receive variables brightness
and/or transition
.
Defines an action to run when the light is given a hs color command. Available variables: hs
as a tuple, h
and s
Defines an action to run when the light is given an RGB color command. Available variables: rgb
as a tuple, r
, g
and b
.
Defines an action to run when the light is given an RGBW color command. Available variables: rgbw
as a tuple, rgb
as a tuple, r
, g
, b
and w
.
Defines an action to run when the light is given an RGBWW color command. Available variables: rgbww
as a tuple, rgb
as a tuple, r
, g
, b
, cw
and ww
.
Defines an action to run when the light is given an effect command. Receives variable effect
. May also receive variables brightness
and/or transition
.
Legacy Lock configuration format
This format still works but is no longer recommended. Use modern configuration.
This format is configured as a platform for the lock
integration and not directly under the template
integration.
Configuration Variables
An ID that uniquely identifies this lock. Set this to a unique value to allow customization through the UI.
Defines a template to set the state of the lock.
Defines a template to get the available
state of the entity. If the template either fails to render or returns True
, "1"
, "true"
, "yes"
, "on"
, "enable"
, or a non-zero number, the entity will be available
. If the template returns any other value, the entity will be unavailable
. If not configured, the entity will always be available
. Note that the string comparison not case sensitive; "TrUe"
and "yEs"
are allowed.
Defines a template to get the code_format
attribute of the entity. This template must evaluate to a valid Python regular expressionNone
. If it evaluates to a not-None
value, the user is prompted to enter a code when interacting with the lock. The code will be matched against the regular expression, and only if it matches, the lock/unlock actions will be executed. The actual validity of the entered code must be verified within these actions. If there’s a syntax error in the template, the entity will be unavailable. If the template fails to render for other reasons or if the regular expression is invalid, no code will be accepted and the lock/unlock actions will never be invoked.
Defines an action to run when the lock is locked.
Defines an action to run when the lock is unlocked.
Defines an action to run when the lock is opened.
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.
Configuration Variables
Map of your sensors.
Defines a template for the name to be used in the frontend (this overrides friendly_name).
An ID that uniquely identifies this sensor. Set this to a unique value to allow customization through the UI.
Defines the units of measurement of the sensor, if any. This will also display the value based on the user profile Number Format setting and influence the graphical presentation in the history visualization as a continuous value.
Defines a template to get the state of the sensor.
Defines a template for the icon of the sensor.
Defines a template for the entity picture of the sensor.
Defines templates for attributes of the sensor.
The attribute and corresponding template.
Defines a template to get the available
state of the integration. If the template returns true
, the device is available
. If the template returns any other value, the device will be unavailable
. If availability_template
is not configured, the integration will always be available
.
Sets the class of the device, changing the device state and icon that is displayed on the UI (see below). It does not set the unit_of_measurement
.
Legacy Switch configuration format
This format still works but is no longer recommended. Use modern configuration.
This format is configured as a platform for the switch
integration and not directly under the template
integration.
Configuration Variables
List of your switches.
An ID that uniquely identifies this switch. Set this to a unique value to allow customization through the UI.
Defines a template to set the state of the switch. If not defined, the switch will optimistically assume all commands are successful.
Defines a template to get the available
state of the entity. If the template either fails to render or returns True
, "1"
, "true"
, "yes"
, "on"
, "enable"
, or a non-zero number, the entity will be available
. If the template returns any other value, the entity will be unavailable
. If not configured, the entity will always be available
. Note that the string comparison not case sensitive; "TrUe"
and "yEs"
are allowed.
Defines an action or list of actions to run when the switch is turned on.
Defines an action or list of actions to run when the switch is turned off.
Defines a template for the icon of the switch.
Defines a template for the picture of the switch.
Legacy Vacuum configuration format
This format still works but is no longer recommended. Use modern configuration.
This format is configured as a platform for the vacuum
integration and not directly under the template
integration.
Configuration Variables
List of your vacuums.
An ID that uniquely identifies this vacuum. Set this to a unique value to allow customization through the UI.
Defines a template to get the state of the vacuum. Valid value: docked
/cleaning
/idle
/paused
/returning
/error
Defines a template to get the battery level of the vacuum. Legal values are numbers between 0
and 100
.
Defines a template to get the fan speed of the vacuum.
Defines templates for attributes of the sensor.
The attribute and corresponding template.
Defines a template to get the available
state of the entity. If the template either fails to render or returns True
, "1"
, "true"
, "yes"
, "on"
, "enable"
, or a non-zero number, the entity will be available
. If the template returns any other value, the entity will be unavailable
. If not configured, the entity will always be available
. Note that the string comparison not case sensitive; "TrUe"
and "yEs"
are allowed.
Defines an action to run when the vacuum is started.
Defines an action to run when the vacuum is paused.
Defines an action to run when the vacuum is stopped.
Defines an action to run when the vacuum is given a return to base command.
Defines an action to run when the vacuum is given a clean spot command.
Defines an action to run when the vacuum is given a locate command.
Defines an action to run when the vacuum is given a command to set the fan speed.
Legacy Weather configuration format
This format still works but is no longer recommended. Use modern configuration.
This format is configured as a platform for the weather
integration and not directly under the template
integration.
Configuration Variables
Name to use in the frontend.
An ID that uniquely identifies this weather entity. Set this to a unique value to allow customization through the UI.
The current weather condition.
The current temperature.
The current dew point.
The current apparent (feels-like) temperature.
Unit for temperature_template output. Valid options are °C, °F, and K.
The current humidity.
The current air pressure.
Unit for pressure_template output. Valid options are Pa, hPa, kPa, bar, cbar, mbar, mmHg, inHg, psi.
The current wind speed.
The current wind gust speed.
Unit for wind_speed_template output. Valid options are m/s, km/h, mph, mm/d, in/d, and in/h.
The current wind bearing.
The current ozone level.
The current cloud coverage.
The current visibility.
Unit for visibility_template output. Valid options are km, mi, ft, m, cm, mm, in, yd.
Daily forecast data.
Hourly forecast data.
Twice daily forecast data.