2025.6.1
Home ▸ Integrations ▸

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

Looking for your configuration file?
fans map Required

List of your fans.

friendly_name string (Optional)

Name to use in the frontend.

unique_id string (Optional)

An ID that uniquely identifies this fan. Set this to a unique value to allow customization through the UI.

value_template template Required

Defines a template to get the state of the fan. Valid values: on, off

percentage_template template (Optional)

Defines a template to get the speed percentage of the fan.

preset_mode_template template (Optional)

Defines a template to get the preset mode of the fan.

oscillating_template template (Optional)

Defines a template to get the osc state of the fan. Valid values: true, false

direction_template template (Optional)

Defines a template to get the direction of the fan. Valid values: forward, reverse

availability_template template (Optional, default: true)

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.

turn_on action Required

Defines an action to run when the fan is turned on.

turn_off action Required

Defines an action to run when the fan is turned off.

set_percentage action (Optional)

Defines an action to run when the fan is given a speed percentage command.

set_preset_mode action (Optional)

Defines an action to run when the fan is given a preset command.

set_oscillating action (Optional)

Defines an action to run when the fan is given an osc state command.

set_direction action (Optional)

Defines an action to run when the fan is given a direction command.

preset_modes string | list (Optional, default: [])

List of preset modes the fan is capable of. This is an arbitrary list of strings and must not contain any speeds.

speed_count integer (Optional, default: 100)

The number of speeds the fan supports. Used to calculate the percentage step for the fan.increase_speed and fan.decrease_speed actions.

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 %}

Related topics