Switch Component

The switch domain includes all platforms that should show up like a switch and can only be turned ON or OFF.

Base Switch Configuration

switch:
  - platform: ...
    name: "Switch Name"
    icon: "mdi:restart"

Configuration variables:

  • id (Optional, string): Manually specify the ID for code generation. At least one of id and name must be specified.

  • name (Optional, string): The name of the switch. At least one of id and name must be specified.

    Note

    If you have a friendly_name set for your device and you want the switch to use that name, you can set name: None.

  • icon (Optional, icon): Manually set the icon to use for the sensor in the frontend.

  • inverted (Optional, boolean): Whether to invert the binary state, i.e. report ON states as OFF and vice versa. Defaults to false.

  • internal (Optional, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an id without a name will implicitly set this to true.

  • restore_mode (Optional): Control how the switch attempts to restore state on bootup. NOTE : Not all components consider restore_mode. Check the documentation of the specific component to understand how this feature works for a particular component or device. For restoring on ESP8266s, also see restore_from_flash in the esp8266 section.

    • RESTORE_DEFAULT_OFF - Attempt to restore state and default to OFF if not possible to restore.

    • RESTORE_DEFAULT_ON - Attempt to restore state and default to ON.

    • RESTORE_INVERTED_DEFAULT_OFF - Attempt to restore state inverted from the previous state and default to OFF.

    • RESTORE_INVERTED_DEFAULT_ON - Attempt to restore state inverted from the previous state and default to ON.

    • ALWAYS_OFF (Default) - Always initialize the switch as OFF on bootup.

    • ALWAYS_ON - Always initialize the switch as ON on bootup.

    • DISABLED - Does nothing and leaves it up to the downstream platform component to decide. For example, the component could read hardware and determine the state, or have a specific configuration option to regulate initial state.

    Unless a specific platform defines another default value, the default is ALWAYS_OFF.

  • on_turn_on (Optional, Action): An automation to perform when the switch is turned on. See switch.on_turn_on / switch.on_turn_off Trigger.

  • on_turn_off (Optional, Action): An automation to perform when the switch is turned off. See switch.on_turn_on / switch.on_turn_off Trigger.

  • disabled_by_default (Optional, boolean): If true, then this entity should not be added to any client’s frontend, (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to false.

  • entity_category (Optional, string): The category of the entity. See https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. Set to "" to remove the default entity category.

  • device_class (Optional, string): The device class for the switch. See https://www.home-assistant.io/integrations/switch/#device-class for a list of available options.

  • If MQTT enabled, All other options from MQTT Component.

  • If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See Webserver Version 3.

switch.toggle Action

This action toggles a switch with the given ID when executed.

on_...:
  then:
    - switch.toggle: relay_1

switch.turn_on Action

This action turns a switch with the given ID on when executed.

on_...:
  then:
    - switch.turn_on: relay_1

switch.turn_off Action

This action turns a switch with the given ID off when executed.

on_...:
  then:
    - switch.turn_off: relay_1

switch.is_on / switch.is_off Condition

This Condition checks if the given switch is ON (or OFF).

# In some trigger:
on_...:
  if:
    condition:
      # Same syntax for is_off
      switch.is_on: my_switch

lambda calls

From lambdas, you can call several methods on all switches to do some advanced stuff (see the full API Reference for more info).

  • publish_state(): Manually cause the switch to publish a new state and store it internally. If it’s different from the last internal state, it’s additionally published to the frontend.

    // Within lambda, make the switch report a specific state
id(my_switch).publish_state(false);
id(my_switch).publish_state(true);

    Note

    Keep in mind that this does not change the actual state of the switch. It only changes the state in the frontend and the internal state. If you want to change the actual state of the switch, you need to call turn_on(), turn_off() or toggle().

    For example, if you are using a GPIO Switch, calling publish_state() will not change the GPIO pin level. To do that, you need to call turn_on(), turn_off() or toggle(). The same applies to other switch platforms.

  • state: Retrieve the current state of the switch.

    // Within lambda, get the switch state and conditionally do something
if (id(my_switch).state) {
  // Switch is ON, do something here
} else {
  // Switch is OFF, do something else here
}

  • turn_off()/turn_on(): Manually turn the switch ON/OFF from code. Similar to the switch.turn_on and switch.turn_off actions, but can be used in complex lambda expressions.

    id(my_switch).turn_off();
id(my_switch).turn_on();
// Toggle the switch
id(my_switch).toggle();

switch.on_turn_on / switch.on_turn_off Trigger

This trigger is activated each time the switch is turned on. It becomes active right after the switch component has acknowledged the state (e.g. after it switched ON/OFF itself).

switch:
  - platform: gpio  # or any other platform
    # ...
    on_turn_on:
    - logger.log: "Switch Turned On!"
    on_turn_off:
    - logger.log: "Switch Turned Off!"

See Also