Skip to main content
Category: Controls · Sends commands: yes · Reads data: no

​
Mental model

A Switch is a light switch. It holds a state — on or off — and sends a command each time you flip it. Unlike a Button (a one-shot), a Switch represents a persistent state your device should be in.

​
When to use it

  • Turn something on and keep it on (a relay, a fan, a mode)
  • Any binary state the user sets and the device holds

​
Settings

​
General

  • Widget Title / ID
  • Initial state — ON or OFF at load
  • ON text / OFF text · ON label / OFF label — the state text and labels
  • Show text labels · show icon · icon size

​
Style

Status color, label color, container shape (pill / rounded / square), plus the common border/font/background controls.

​
Triggers

A Switch usually needs two triggers — one for on, one for off. Events:
EventFires when
onToggled on
offToggled off
toggleEither direction (carries the new boolean)
changeState changed
clickPressed
(common)load, ready, destroy, update, visible, hidden

​
Example — toggle a relay

Triggers: 
Trigger 1:  WHEN on  → Current Device → Operate → ON   { "relay": 1 }
Trigger 2:  WHEN off → Current Device → Operate → OFF  { "relay": 1 }
Firmware (Arduino): 
device.setUserCommandHandler([](JsonObject &msg) {
  if (!device.findAction(msg, "Operate", "ON").isNull())  digitalWrite(RELAY, HIGH);
  if (!device.findAction(msg, "Operate", "OFF").isNull()) digitalWrite(RELAY, LOW);
});

​
Reflecting real device state

To make the Switch show the device’s actual state (not just what the user tapped), push the state back from firmware to the Switch’s widget ID: 
device.updateWidget(targetId, "relaySwitch", String(isOn ? "on" : "off"));

​
Script API example

The same interactions from a dashboard script: 
widget.on('relaySwitch', 'toggle', (isOn) => {
  widget.setText('stateLabel', isOn ? 'ON' : 'OFF');
  ws.send(context.deviceId, { relay: isOn ? 1 : 0 });
});

Triggers in full

Wiring the on/off commands.

Button

For one-shot actions instead of state.