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

# Events

> The widget event system — subscribe, emit, and clean up.

Widgets fire events you can subscribe to from a script via
[`widget.on` / `widget.once` / `widget.off` / `widget.emit`](/script/widgets-api#events).

## Subscribing

```js theme={null}
// Returns an unsubscribe function
const off = widget.on('mySlider', 'change', (value) => {
  console.log('slider is now', value);
});

// One-time
widget.once('myWidget', 'ready', () => { /* ... */ });

// Stop listening
off();
widget.off('mySlider', 'change');   // remove all 'change' handlers
```

## Emitting

```js theme={null}
widget.emit('myWidget', 'update', newValue);
```

## Event types

The full vocabulary, by group:

| Group             | Events                                                                                       |
| ----------------- | -------------------------------------------------------------------------------------------- |
| Interaction       | `click`, `doubleclick`, `longpress`, `hover`, `focus`, `blur`                                |
| Button            | `push`, `release`                                                                            |
| Input             | `change`, `input`, `submit`, `keydown`, `keyup`, `keypress`                                  |
| Slider / Range    | `slideStart`, `slide`, `slideEnd`                                                            |
| Switch / Toggle   | `toggle`, `on`, `off`                                                                        |
| Lifecycle         | `load`, `ready`, `destroy`, `update`                                                         |
| State             | `error`, `success`, `loading`, `loaded`                                                      |
| Selection         | `select`, `deselect`, `optionchange`                                                         |
| Touch / Gesture   | `touchstart`, `touchend`, `swipeleft`, `swiperight`, `swipeup`, `swipedown`, `pinch`, `zoom` |
| Drag              | `dragstart`, `drag`, `dragend`                                                               |
| Timer / Animation | `timeout`, `interval`, `animationstart`, `animationend`                                      |
| Data              | `dataload`, `datafail`, `refresh`                                                            |

<Note>
  Not every widget fires every event — a Switch fires `toggle`/`on`/`off`, a Slider
  fires `slide*`. Lifecycle events (`load`, `ready`, `destroy`) apply to all.
</Note>

## Cleanup

Always keep the unsubscribe functions from `on`/`once` if your script sets up
long-lived listeners, and call them when no longer needed to avoid duplicate
handlers across re-runs.

<Card title="See widget API" icon="gauge" href="/script/widgets-api">
  The methods these events pair with.
</Card>