> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperwisor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Button

> A momentary control that sends a command when pressed — full settings, triggers, and firmware examples.

<Info>
  **Category:** Controls · **Sends commands:** yes · **Reads data:** no
</Info>

## 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](/dashboard/widgets/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](/dashboard/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](/dashboard/triggers). 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:

```cpp theme={null}
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](/script/overview):

```js theme={null}
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 }));
```

<CardGroup cols={2}>
  <Card title="Triggers in full" icon="bolt" href="/dashboard/triggers">
    The WHEN → SEND TO → EXECUTE → Action model.
  </Card>

  <Card title="Switch" icon="toggle-on" href="/dashboard/widgets/switch">
    For on/off state instead of a one-shot.
  </Card>
</CardGroup>