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
- Button
- Select
- MultiSelect
- Toggle
- Checkbox
- RadioGroup
- TabGroup
- TextInput
- TextArea
- SearchInput
- NumberInput
- DateInput
- SliderInput
- RangeInput
- SecretInput
- Div
- Marquee
- 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, outline, danger, warning, icon |
size | string | ❌ | null | Size: xs, sm, lg, xl |
data | object | ❌ | {} | Extra data payload sent with event |
disabled | boolean | ❌ | false | Disable the button |
description | string | ❌ | "" | Tooltip on hover |
Event Emitted
{
componentId: "button-abc123", // Auto-generated component ID
...data // Your custom data object spread in
}
Auto-Wired Actions
When event follows elementId:action pattern, these actions work automatically:
| Event Pattern | Behavior |
|---|---|
myId:increment | Finds id="myId", parses as number, adds 1 |
myId:decrement | Finds id="myId", parses as number, subtracts 1 |
myId:reset | Finds id="myId", sets to 0 |
myId:toggle | Finds id="myId", toggles true/false |
Example
{
"type": "button",
"label": "Submit",
"event": "form:submit",
"variant": "primary",
"data": {"formId": "contact"}
}
Select
A single-select dropdown.
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
type | "select" | ✅ YES | - | Component type identifier |
event | string | ✅ YES | - | Event name (format: namespace:action) |
options | array | ✅ YES | - | Array of {label, value} objects |
selected | string | ❌ | "" | Initially selected value |
label | string | ❌ | "" | Label text |
searchable | boolean | ❌ | false | Enable search filtering |
disabled | boolean | ❌ | false | Disable the dropdown |
Event Emitted
{
value: "selected_value", // The selected option's value
componentId: "select-abc123"
}
Example
{
"type": "select",
"label": "Theme:",
"event": "theme:change",
"options": [
{"label": "Dark", "value": "dark"},
{"label": "Light", "value": "light"},
{"labe