Button

Category: Controls · Sends commands: yes · Reads data: no

Mental model

A Button is a doorbell. Pressing it fires a one-shot signal — it doesn’t hold a state, it just acts. Use it for “do this now”: start, reset, open, trigger. If you need something that stays on or off, use a Switch instead.

When to use it

Fire a one-time command (START, RESET, OPEN, CAPTURE)
A momentary action that reverts on release (push / release)
Any “press to do X” interaction

Settings

General

Widget Title / ID — the ID is how firmware and triggers address it (see The General Tab)
Normal text / Pressed text — label in each state
Button icon · icon size · icon position — an optional icon
Button shape · size — pill / rounded / square; sizing

Style

Full appearance controls — background (incl. gradient), border (color / width / radius), font (family / size / weight), padding, box shadow, and hover/active scale and animation for press feedback.

Triggers

The Button’s whole purpose. Configure what it sends in the Triggers tab. Events it can fire:

Event	Fires when
`click`	A normal press
`doubleclick`	Two quick presses
`longpress`	Held down
`push`	The moment it’s pressed
`release`	The moment it’s let go
`hover`	Pointer over it
(common)	`load`, `ready`, `destroy`, `update`, `visible`, `hidden`

Example — a button that starts a device

Trigger (in the Triggers tab):

WHEN     click
SEND TO  Current Device
EXECUTE  Operate
Action   START   params: {}

Firmware (Arduino) — handle it:

device.setUserCommandHandler([](JsonObject &msg) {
  JsonObject start = device.findAction(msg, "Operate", "START");
  if (!start.isNull()) {
    // start the motor / pump / process
  }
});

Momentary (hold-to-run) pattern

Use push and release as two triggers to run only while held:

Trigger 1:  WHEN push    → Current Device → Motor → FORWARD
Trigger 2:  WHEN release → Current Device → Motor → STOP

Script API example

The same interactions from a dashboard script:

widget.on('startButton', 'click', () => {
  ws.send(context.deviceId, { command: 'START' });
});

// Hold-to-run via push / release
widget.on('startButton', 'push',    () => ws.send(context.deviceId, { motor: 1 }));
widget.on('startButton', 'release', () => ws.send(context.deviceId, { motor: 0 }));

Triggers in full

The WHEN → SEND TO → EXECUTE → Action model.

Switch

For on/off state instead of a one-shot.

Designer

Widget Reference

Mental model

When to use it

Settings

General

Style

Triggers

Example — a button that starts a device

Momentary (hold-to-run) pattern

Script API example

Triggers in full

Switch

​Mental model

​When to use it

​Settings

​General

​Style

​Triggers

​Example — a button that starts a device

​Momentary (hold-to-run) pattern

​Script API example

Triggers in full

Switch

Mental model

When to use it

Settings

General

Style

Triggers

Example — a button that starts a device

Momentary (hold-to-run) pattern

Script API example