Template fan
The Template integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] creates fans that combine integrations and provides the
ability to run scripts or invoke actions for each of the turn_on, turn_off, set_percentage,
set_preset_mode, set_oscillating, and set_direction commands of a fan.
Configuration
To enable template fans in your installation, add the following to your
configuration.yamlThe 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] file:
# Example configuration.yaml entry
fan:
- platform: template
fans:
bedroom_fan:
friendly_name: "Bedroom fan"
value_template: "{{ states('input_boolean.state') }}"
percentage_template: "{{ states('input_number.percentage') }}"
preset_mode_template: "{{ states('input_select.preset_mode') }}"
oscillating_template: "{{ states('input_select.osc') }}"
direction_template: "{{ states('input_select.direction') }}"
turn_on:
action: script.fan_on
turn_off:
action: script.fan_off
set_percentage:
action: script.fans_set_speed
data:
percentage: "{{ percentage }}"
set_preset_mode:
action: script.fans_set_preset_mode
data:
preset_mode: "{{ preset_mode }}"
set_oscillating:
action: script.fan_oscillating
data:
oscillating: "{{ oscillating }}"
set_direction:
action: script.fan_direction
data:
direction: "{{ direction }}"
speed_count: 6
preset_modes:
- 'auto'
- 'smart'
- 'whoosh'
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.
Template and action variables
State-based template entities have the special template variable this available in their templates and actions. The this variable aids self-referencing of an entity’s state and attribute in templates and actions.
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
Examples
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.
fan:
- platform: template
fans:
helper_fan:
friendly_name: "Helper Fan"
value_template: "{{ states('input_boolean.state') }}"
turn_on:
- action: input_boolean.turn_on
target:
entity_id: input_boolean.state
turn_off:
- action: input_boolean.turn_off
target:
entity_id: input_boolean.state
percentage_template: >
{{ states('input_number.percentage') if is_state('input_boolean.state', 'on') else 0 }}
speed_count: 6
set_percentage:
- action: input_boolean.turn_{{ 'on' if percentage > 0 else 'off' }}
target:
entity_id: input_boolean.state
- action: input_number.set_value
target:
entity_id: input_number.percentage
data:
value: "{{ percentage }}"
Preset modes fan
This example uses an existing fan with only a percentage. It extends the percentage value into useable preset modes without a helper entity.
fan:
- platform: template
fans:
preset_mode_fan:
friendly_name: "Preset Mode Fan Example"
value_template: "{{ states('fan.percentage_fan') }}"
turn_on:
- action: fan.turn_on
target:
entity_id: fan.percentage_fan
turn_off:
- action: fan.turn_off
target:
entity_id: fan.percentage_fan
percentage_template: >
{{ state_attr('fan.percentage_fan', 'percentage') }}
speed_count: 3
set_percentage:
- action: fan.set_percentage
target:
entity_id: fan.percentage_fan
data:
percentage: "{{ percentage }}"
preset_modes:
- "off"
- "low"
- "medium"
- "high"
preset_mode_template: >
{% if is_state('fan.percentage_fan', 'on') %}
{% if state_attr('fan.percentage_fan', 'percentage') == 100 %}
high
{% elif state_attr('fan.percentage_fan', 'percentage') == 66 %}
medium
{% else %}
low
{% endif %}
{% else %}
off
{% endif %}
set_preset_mode:
- action: fan.set_percentage
target:
entity_id: fan.percentage_fan
data:
percentage: >-
{% if preset_mode == 'high' %}
100
{% elif preset_mode == 'medium' %}
66
{% elif preset_mode == 'low' %}
33
{% else %}
0
{% endif %}