Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt

Use this file to discover all available pages before exploring further.

ESPHome’s switch domain represents any output that has exactly two states — on or off — and exposes it as a Home Assistant switch entity. The most common use is controlling relay modules, but switches also power template logic, UART sequences, and output-pin abstractions. Every switch platform inherits a common set of configuration variables for naming, state restoration, and automation triggers.

​
Base Switch Configuration

switch:
  - platform: gpio
    pin: GPIO5
    name: "Irrigation Pump"
    device_class: switch
    restore_mode: RESTORE_DEFAULT_OFF
    on_turn_on:
      - logger.log: "Pump started"
    on_turn_off:
      - logger.log: "Pump stopped"
​
id
string
Manually specify the ID for code generation. At least one of id and name must be specified.
​
name
string
The name for the switch in Home Assistant. Set to None to inherit the device’s friendly_name.
​
icon
icon
Manually override the MDI icon shown in the frontend.
​
inverted
boolean
If true, the reported state is inverted (ON becomes OFF and vice versa). Defaults to false.
​
restore_mode
enum
Controls the initial switch state on boot:
  • ALWAYS_OFF (default) — always start off.
  • ALWAYS_ON — always start on.
  • RESTORE_DEFAULT_OFF — restore previous state, default to off.
  • RESTORE_DEFAULT_ON — restore previous state, default to on.
  • RESTORE_INVERTED_DEFAULT_OFF — restore inverted state, default to off.
  • RESTORE_INVERTED_DEFAULT_ON — restore inverted state, default to on.
  • DISABLED — leave initial state to the underlying platform.
​
device_class
string
The Home Assistant device class for the switch. Controls icon behavior in the frontend.
​
internal
boolean
If true, the switch is not exposed to the frontend. Defaults to false.
​
disabled_by_default
boolean
If true, the entity is hidden in Home Assistant until manually enabled. Defaults to false.
​
entity_category
string
The entity category (config, diagnostic). Set to "" to remove the default.

​
Switch Actions

​
switch.turn_on

on_...:
  - switch.turn_on: relay_1

​
switch.turn_off

on_...:
  - switch.turn_off: relay_1

​
switch.toggle

on_...:
  - switch.toggle: relay_1

​
switch.control

Useful when the desired state is computed dynamically. 
on_...:
  - switch.control:
      id: relay_1
      state: !lambda "return id(motion_sensor).state;"
​
id
ID
required
The switch to control.
​
state
boolean (templatable)
required
true to turn on, false to turn off. Accepts lambda expressions.

​
switch.is_on / switch.is_off Condition

on_...:
  if:
    condition:
      switch.is_on: relay_1
    then:
      - switch.turn_off: relay_1

​
Switch Triggers

​
on_turn_on / on_turn_off

Fire after the switch acknowledges the new state. 
switch:
  - platform: gpio
    pin: GPIO5
    name: "Boiler"
    on_turn_on:
      - logger.log: "Boiler ON"
    on_turn_off:
      - logger.log: "Boiler OFF"

​
on_state

Fires on any state change. The new state is available as boolean x. 
switch:
  - platform: gpio
    pin: GPIO5
    name: "Fan"
    on_state:
      - light.control:
          id: fan_indicator_led
          state: !lambda "return x;"

​
Lambda Calls

// Read state
if (id(my_switch).state) { /* ON */ }

// Change state
id(my_switch).turn_on();
id(my_switch).turn_off();
id(my_switch).toggle();
id(my_switch).control(true);

// Publish a state without changing hardware
id(my_switch).publish_state(true);
publish_state() only changes the reported state — it does not affect the underlying hardware. Use turn_on(), turn_off(), or toggle() to actually change the output.

GPIO Switch

Control a digital GPIO pin directly. Ideal for relay modules, LEDs, and other digital loads.

Template Switch

Synthesize a switch from C++ lambdas. Useful for virtual switches and complex logic.

Output Switch

Wrap any output component as a switch entity. Bridges low-level outputs to the switch domain.

Restart Switch

Trigger a device restart from Home Assistant. Always useful for remote management.

Shutdown Switch

Gracefully shut down the device. Useful for battery-powered devices.

Safe Mode Switch

Boot into safe mode. Allows recovery when a bad config prevents normal operation.

UART Switch

Send a configured UART byte sequence when the switch is toggled.

Modbus Switch

Control Modbus coil registers over RS-485, exposing them as Home Assistant switches.

​
Complete Example: Timed Relay with Interlock

switch:
  - platform: gpio
    pin: GPIO5
    id: relay_a
    name: "Relay A"
    restore_mode: ALWAYS_OFF
    interlock: [relay_b]       # only one can be on at a time
    interlock_wait_time: 200ms

  - platform: gpio
    pin: GPIO6
    id: relay_b
    name: "Relay B"
    restore_mode: ALWAYS_OFF
    interlock: [relay_a]
    interlock_wait_time: 200ms

  - platform: template
    name: "Timed Pump (5 min)"
    turn_on_action:
      - switch.turn_on: relay_a
      - delay: 5min
      - switch.turn_off: relay_a
    turn_off_action:
      - switch.turn_off: relay_a

Build docs developers (and LLMs) love

Get started for freeTalk to us