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

# widget

> Read and control dashboard widgets from a script.

The `widget` global reads and controls widgets by their **widget ID**. (It's
singular — `widget`, not `widgets`.)

## Values and text

```js theme={null}
widget.setValue(widgetId, value);          // set the widget's value
const v = widget.getValue(widgetId);       // read it
widget.setText(widgetId, text);            // set displayed text
const t = widget.getText(widgetId);        // read it
```

## Visibility

```js theme={null}
widget.show(widgetId);
widget.hide(widgetId);
```

## Position, size, rotation

```js theme={null}
widget.setPosition(widgetId, x, y);
widget.getPosition(widgetId);              // { x, y } | undefined
widget.setSize(widgetId, width, height);
widget.getSize(widgetId);                  // { width, height } | undefined
widget.resize(widgetId, width, height);
widget.move(widgetId, x, y);
widget.setRotation(widgetId, degrees);
widget.getRotation(widgetId);              // number | undefined
```

## Config

```js theme={null}
widget.setConfig(widgetId, configKey, value);
widget.getConfig(widgetId, configKey);     // one key
widget.getConfig(widgetId);                // whole config object
```

## The widget object

```js theme={null}
const w = widget.get(widgetId);            // DashboardWidget | undefined
```

## Events

Subscribe to widget events. `on` and `once` return an unsubscribe function.

```js theme={null}
const off = widget.on(widgetId, 'change', (value) => { /* ... */ });
widget.once(widgetId, 'ready', () => { /* ... */ });
widget.off(widgetId, 'change');            // remove handlers for an event
widget.emit(widgetId, 'change', value);    // emit programmatically
off();                                      // unsubscribe
```

See [Events](/script/events) for the full event vocabulary.

<Card title="Events reference" icon="bolt" href="/script/events">
  Every event type a widget can fire.
</Card>