PyWry

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, 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