/component_reference

PyWry Component Reference - MANDATORY SYNTAX

> **STOP. THIS IS THE AUTHORITATIVE REFERENCE FOR ALL COMPONENTS.** > **YOU MUST USE THE EXACT EVENT SIGNATURES DOCUMENTED HERE.** > **THERE ARE NO EXCEPTIONS. NO WORKAROUNDS. NO DEVIATIONS.**

---

CRITICAL: System Events for Widget Updates

These are the ONLY events that work for updating widgets. Use `send_event` tool with these event types:

AG Grid Data Updates

| Event Type | Payload | Description | |------------|---------|-------------| | `grid:update-data` | `{"data": [...rows...], "strategy": "set"}` | Replace all rows | | `grid:update-data` | `{"data": [...rows...], "strategy": "append"}` | Append rows | | `grid:update-data` | `{"data": [...rows...], "strategy": "update"}` | Update existing rows | | `grid:update-columns` | `{"columnDefs": [...]}` | Update column definitions | | `grid:update-cell` | `{"rowId": "row-1", "colId": "price", "value": 99.50}` | Update single cell |

AG Grid State Persistence

| Event Type | Payload | Description | |------------|---------|-------------| | `grid:request-state` | `{}` | Request current grid state | | `grid:request-state` | `{"gridId": "my-grid"}` | Request specific grid's state | | `grid:restore-state` | `{"state": {...savedState...}}` | Restore saved grid state | | `grid:reset-state` | `{"hard": false}` | Soft reset (keeps column order) | | `grid:reset-state` | `{"hard": true}` | Hard reset (full reset) |

**Response Event:** `grid:state-response` with `{"gridId": "...", "state": {...}}`

**State Object Contents:**

• Column state (width, order, visibility, pinned, sort)
• Filter state (active filters per column)
• Sort state (sorted columns and direction)

Plotly Chart Updates

| Event Type | Payload | Description | |------------|---------|-------------| | `plotly:update-figure` | `{"data": [...], "layout": {...}}` | Full figure update | | `plotly:update-layout` | `{"layout": {...}}` | Layout only update | | `plotly:reset-zoom` | `{}` | Reset chart zoom to original |

Plotly State Persistence

| Event Type | Payload | Description | |------------|---------|-------------| | `plotly:request-state` | `{}` | Request current chart state | | `plotly:request-state` | `{"chartId": "my-chart"}` | Request specific chart's state |

**Response Event:** `plotly:state-response` with `{"chartId": "...", "data": [...], "layout": {...}}`

Plotly Data Export

| Event Type | Payload | Description | |------------|---------|-------------| | `plotly:export-data` | `{}` | Export chart data | | `plotly:export-data` | `{"chartId": "my-chart"}` | Export specific chart's data |

**Response Event:** `plotly:export-response` with `{"data": [{"traceIndex": 0, "name": "...", "x": [...], "y": [...], "type": "..."}]}`

DOM Content Updates

| Event Type | Payload | Description | |------------|---------|-------------| | `pywry:set-content` | `{"id": "elementId", "text": "..."}` | Set text content | | `pywry:set-content` | `{"id": "elementId", "html": "..."}` | Set HTML content | | `pywry:set-style` | `{"id": "elementId", "styles": {"color": "red"}}` | Update CSS styles |

Theme Updates

| Event Type | Payload | Description | |------------|---------|-------------| | `pywry:update-theme` | `{"theme": "dark"}` | Switch theme (dark/light/system) | | `pywry:update-theme` | `{"theme": "ag-theme-alpine-dark"}` | AG Grid theme | | `pywry:update-theme` | `{"theme": "plotly_dark"}` | Plotly template |

Toast Notifications

Use `show_toast` tool instead, or:

| Event Type | Payload | Description | |------------|---------|-------------| | `pywry:alert` | `{"message": "...", "type": "info"}` | info, success, warning, error |

Toolbar Component State (Get/Set Values)

| Event Type | Payload | Description | |------------|---------|-------------| | `toolbar:set-value` | `{"componentId": "my-select", "value": "option2"}` | Set single component value | | `toolbar:set-values` | `{"values": {"select-1": "A", "toggle-1": true}}` | Set multiple values at once | | `toolbar:request-state` | `{"componentId": "my-input"}` | Request single component value | | `toolbar:request-state` | `{"toolbarId": "top-toolbar"}` | Request all values in toolbar | | `toolbar:request-state` | `{}` | Request all toolbar values |

**Response Event:** `toolbar:state-response` with `{"componentId": "...", "value": ...}` or `{"values": {...}}`

**Supported Components for set-value:**

• `select`: `{"componentId": "id", "value": "option-value"}`
• `multiselect`: `{"componentId": "id", "value": ["a", "b"]}`
• `toggle`: `{"componentId": "id", "value": true}`
• `checkbox`: `{"componentId": "id", "value": true}`
• `text/textarea/search`: `{"componentId": "id", "value": "text"}`
• `number`: `{"componentId": "id", "value": 42}`
• `slider`: `{"componentId": "id", "value": 50}`
• `range`: `{"componentId": "id", "value": {"start": 10, "end": 90}}`
• `tabs/radio`: `{"componentId": "id", "value": "tab-value"}`

**Note:** `secret` inputs cannot be set via toolbar:set-value for security.

---

Table of Contents

1. [Button](#button) 2. [Select](#select) 3. [MultiSelect](#multiselect) 4. [Toggle](#toggle) 5. [Checkbox](#checkbox) 6. [RadioGroup](#radiogroup) 7. [TabGroup](#tabgroup) 8. [TextInput](#textinput) 9. [TextArea](#textarea) 10. [SearchInput](#searchinput) 11. [NumberInput](#numberinput) 12. [DateInput](#dateinput) 13. [SliderInput](#sliderinput) 14. [RangeInput](#rangeinput) 15. [SecretInput](#secretinput) 16. [Div](#div) 17. [Marquee](#marquee) 18. [TickerItem](#tickeritem)

---

Button

A clickable button that emits an event.

Properties

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | `type` | `"button"` | ✅ YES | - | Component type identifier | | `label` | `string` | ✅ YES | - | Button text | | `event` | `string` | ✅ YES | - | Event name (format: `namespace:action`) | | `variant` | `string` | ❌ | `"primary"` | Style: `primary`, `secondary`, `neutral`, `ghost`, `ou