home-assistant.io/source/_integrations/fan.template.markdown

title, description, ha_category, ha_release, ha_iot_class, ha_quality_scale, ha_domain

title	description	ha_category	ha_release	ha_iot_class	ha_quality_scale	ha_domain
Template Fan	Instructions how to setup the Template fans within Home Assistant.	Fan	0.69	Local Push	internal	template

The template platform creates fans that combine integrations and provides the ability to run scripts or invoke services 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.yaml file:

{% raw %}

# 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:
          service: script.fan_on
        turn_off:
          service: script.fan_off
        set_percentage:
          service: script.fans_set_speed
          data:
            percentage: "{{ percentage }}"
        set_preset_mode:
          service: script.fans_set_preset_mode
          data:
            preset_mode: "{{ preset_mode }}"
        set_oscillating:
          service: script.fan_oscillating
          data:
            oscillating: "{{ oscillating }}"
        set_direction:
          service: script.fan_direction
          data:
            direction: "{{ direction }}"
        speed_count: 6
        preset_modes:
          - 'auto'
          - 'smart'
          - 'whoosh'

{% endraw %}

{% configuration %} fans: description: List of your fans. required: true type: map keys: friendly_name: description: Name to use in the frontend. required: false type: string unique_id: description: An ID that uniquely identifies this fan. Set this to a unique value to allow customization through the UI. required: false type: string value_template: description: "Defines a template to get the state of the fan. Valid values: on, off" required: true type: template percentage_template: description: Defines a template to get the speed percentage of the fan. required: false type: template preset_mode_template: description: Defines a template to get the preset mode of the fan. required: false type: template oscillating_template: description: "Defines a template to get the osc state of the fan. Valid values: true, false" required: false type: template direction_template: description: "Defines a template to get the direction of the fan. Valid values: forward, reverse" required: false type: template availability_template: description: 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. required: false type: template default: true turn_on: description: Defines an action to run when the fan is turned on. required: true type: action turn_off: description: Defines an action to run when the fan is turned off. required: true type: action set_percentage: description: Defines an action to run when the fan is given a speed percentage command. required: false type: action set_preset_mode: description: Defines an action to run when the fan is given a preset command. required: false type: action set_oscillating: description: Defines an action to run when the fan is given an osc state command. required: false type: action set_direction: description: Defines an action to run when the fan is given a direction command. required: false type: action preset_modes: description: List of preset modes the fan is capable of. This is an arbitrary list of strings and must not contain any speeds. required: false type: [string, list] default: [] speed_count: description: The number of speeds the fan supports. Used to calculate the percentage step for the fan.increase_speed and fan.decrease_speed services. required: false type: integer default: 100 {% endconfiguration %}

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 service calls for set_percentage.

{% raw %}

fan:
  - platform: template
    fans:
      helper_fan:
        friendly_name: "Helper Fan"
        value_template: "{{ states('input_boolean.state') }}"
        turn_on:
          - service: input_boolean.turn_on
            target:
              entity_id: input_boolean.state
        turn_off:
          - service: 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:
          - service: input_boolean.turn_{{ 'on' if percentage > 0 else 'off' }}
            target:
              entity_id: input_boolean.state
          - service: input_number.set_value
            target:
              entity_id: input_number.percentage
            data:
              value: "{{ percentage }}"

{% endraw %}

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.

{% raw %}

fan:
  - platform: template
    fans:
      preset_mode_fan:
        friendly_name: "Preset Mode Fan Example"
        value_template: "{{ states('fan.percentage_fan') }}"
        turn_on:
          - service: fan.turn_on
            target:
              entity_id: fan.percentage_fan
        turn_off:
          - service: fan.turn_off
            target:
              entity_id: fan.percentage_fan
        percentage_template: >
          {{ state_attr('fan.percentage_fan', 'percentage') }}
        speed_count: 3
        set_percentage:
          - service: 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:
          - service: 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 %}

{% endraw %}