> ## 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.

# Countdown Timer

> A configurable countdown that can fire an action when it reaches zero.

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

## Mental model

A **Countdown Timer is an egg timer.** Set a duration, it counts down, and when it
hits zero it can *do something* — notify, play a sound, or fire a command.

## When to use it

* Time-boxed actions (run a pump for 5 minutes, then stop)
* Visible countdowns with a completion event

## Settings

### General

* **Initial duration** — hours / minutes / seconds
* **Auto start** · **show controls**
* **Show progress bar** · **progress color** · **show milliseconds**

### Behavior on complete

* **Execute action on complete** — fire a command at zero
* **Show notification** — title + message
* **Play sound** · **sound URL**

### Style

Background, border, text/icon color, container.

### Triggers

| Event                       | Fires when                                                |
| --------------------------- | --------------------------------------------------------- |
| `complete`                  | The timer reaches zero                                    |
| `start` / `pause` / `reset` | Timer controls                                            |
| *(common)*                  | `load`, `ready`, `destroy`, `update`, `visible`, `hidden` |

## Example — stop a device when time's up

```
WHEN     complete
SEND TO  Current Device
EXECUTE  Operate
Action   OFF   params: {}
```

## Script API example

The same interactions from a [dashboard script](/script/overview):

```js theme={null}
widget.on('runTimer', 'complete', () => {
  ws.send(context.deviceId, { command: 'Operate', action: 'OFF' });
  widget.setText('timerStatus', 'Finished');
});
```

<Card title="Schedule Manager" icon="calendar" href="/dashboard/widgets/schedule">
  For recurring, clock-based automation instead of a one-off countdown.
</Card>