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

AG Grid State Persistence

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

Plotly State Persistence

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

Plotly Data Export

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

DOM Content Updates

Theme Updates

Toast Notifications

Use show_toast tool instead, or:

Toolbar Component State (Get/Set 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
2. Select
3. MultiSelect
4. Toggle
5. Checkbox
6. RadioGroup
7. TabGroup
8. TextInput
9. TextArea
10. SearchInput
11. NumberInput
12. DateInput
13. SliderInput
14. RangeInput
15. SecretInput
16. Div
17. Marquee
18. TickerItem

Button

A clickable button that emits an event.

Properties

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:

Example

{
  "type": "button",
  "label": "Submit",
  "event": "form:submit",
  "variant": "primary",
  "data": {"formId": "contact"}
}

Select

A single-select dropdown.

Properties

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"},
    {"label": "System", "value": "system"}
  ],
  "selected": "dark"
}

MultiSelect

A multi-select dropdown with checkboxes.

Properties

Event Emitted

{
  values: ["value1", "value2"],   // Array of selected values
  componentId: "multiselect-abc123"
}

Example

{
  "type": "multiselect",
  "label": "Columns:",
  "event": "columns:filter",
  "options": [
    {"label": "Name", "value": "name"},
    {"label": "Age", "value": "age"},
    {"label": "City", "value": "city"}
  ],
  "selected": ["name", "age"]
}

Toggle

A toggle switch for boolean values.

Properties

Event Emitted

{
  value: true,                    // Boolean: true or false
  componentId: "toggle-abc123"
}

Example

{
  "type": "toggle",
  "label": "Dark Mode:",
  "event": "theme:toggle",
  "value": true
}

Checkbox

A single checkbox for boolean values.

Properties

Event Emitted

{
  value: true,                    // Boolean: true or false
  componentId: "checkbox-abc123"
}

Example

{
  "type": "checkbox",
  "label": "Enable notifications",
  "event": "settings:notify",
  "value": true
}

RadioGroup

A group of radio buttons for single selection.

Properties

Event Emitted

{
  value: "selected_value",        // The selected option's value
  componentId: "radio-abc123"
}

Example

{
  "type": "radio",
  "label": "View:",
  "event": "view:change",
  "options": [
    {"label": "List", "value": "list"},
    {"label": "Grid", "value": "grid"},
    {"label": "Card", "value": "card"}
  ],
  "selected": "list",
  "direction": "horizontal"
}

TabGroup

Tab-style buttons for single selection (visually different from RadioGroup).

Properties

Event Emitted

{
  value: "selected_value",        // The selected tab's value
  componentId: "tab-abc123"
}

Example

{
  "type": "tabs",
  "label": "Mode:",
  "event": "mode:switch",
  "options": [
    {"label": "Edit", "value": "edit"},
    {"label": "Preview", "value": "preview"},
    {"label": "Split", "value": "split"}
  ],
  "selected": "edit"
}

TextInput

A single-line text input with debounced events.

Properties

Event Emitted

{
  value: "user typed text",       // The current input value
  componentId: "text-abc123"
}

Example

{
  "type": "text",
  "label": "Name:",
  "event": "form:name",
  "placeholder": "Enter your name",
  "debounce": 300
}

TextArea

A multi-line text area with resizing.

Properties

Event Emitted

{
  value: "multi-line\ntext content",  // The textarea content
  componentId: "textarea-abc123"
}

Example

{
  "type": "textarea",
  "label": "Notes:",
  "event": "form:notes",
  "placeholder": "Enter your notes...",
  "rows": 5,
  "resize": "vertical"
}

SearchInput

A search input with magnifying glass icon.

Properties

Event Emitted

{
  value: "search query",          // The search text
  componentId: "search-abc123"
}

Example

{
  "type": "search",
  "label": "Filter:",
  "event": "table:filter",
  "placeholder": "Type to filter...",
  "debounce": 200
}

NumberInput

A numeric input with optional constraints.

Properties

Event Emitted

{
  value: 42,                      // The numeric value
  componentId: "number-abc123"
}

Example

{
  "type": "number",
  "label": "Quantity:",
  "event": "cart:quantity",
  "value": 1,
  "min": 1,
  "max": 100,
  "step": 1
}

DateInput

A date picker input.

Properties

Event Emitted

{
  value: "2025-01-29",            // Date string in YYYY-MM-DD format
  componentId: "date-abc123"
}

Example

{
  "type": "date",
  "label": "Start Date:",
  "event": "filter:startDate",
  "value": "2025-01-01",
  "min": "2020-01-01",
  "max": "2030-12-31"
}

SliderInput

A single-value slider.

Properties

Event Emitted

{
  value: 75,                      // The slider value
  componentId: "slider-abc123"
}

Example

{
  "type": "slider",
  "label": "Volume:",
  "event": "audio:volume",
  "value": 50,
  "min": 0,
  "max": 100,
  "step": 5,
  "show_value": true
}

RangeInput

A dual-handle range slider for min/max selection.

Properties

Event Emitted

{
  start: 25,                      // Start/min value
  end: 75,                        // End/max value
  componentId: "range-abc123"
}

Example

{
  "type": "range",
  "label": "Price Range:",
  "event": "filter:price",
  "start": 100,
  "end": 500,
  "min": 0,
  "max": 1000,
  "step": 10,
  "show_value": true
}

SecretInput

A password/secret input with visibility toggle and copy button.

Properties

Events Emitted

On value change:

{
  value: "base64_encoded_value",  // Base64 encoded secret
  encoded: true,
  componentId: "secret-abc123"
}

On reveal request: (event: {event}:reveal)

{
  componentId: "secret-abc123"
}

On copy request: (event: {event}:copy)

{
  componentId: "secret-abc123"
}

Example

{
  "type": "secret",
  "label": "API Key:",
  "event": "settings:apiKey",
  "placeholder": "Enter your API key",
  "show_toggle": true,
  "show_copy": true
}

Div

A container for custom HTML content.

Properties

Event Emitted

No automatic events. Use for layout/display only, or add interactive children.

Example

{
  "type": "div",
  "content": "<span style=\"color: green\">Online</span>",
  "component_id": "status-display",
  "style": "padding: 8px; font-weight: bold"
}

Marquee

A scrolling text ticker component.

Properties

Event Emitted (when clickable)

{
  value: "the marquee text",      // The text content
  componentId: "marquee-abc123"
}

Update Events

Use set_content or update_marquee tools to update:

// Update text
{id: "marquee-abc123", text: "New content!"}

// Update speed
{id: "marquee-abc123", speed: 10}

// Pause/resume
{id: "marquee-abc123", paused: true}

Example

{
  "type": "marquee",
  "text": "Breaking News: Market is up 5% • Weather: Sunny • More updates...",
  "speed": 20,
  "direction": "left",
  "pause_on_hover": true,
  "clickable": true,
  "event": "news:click"
}

TickerItem

A helper for creating updatable items within a Marquee.

Note: TickerItem is used with build_ticker_item tool, not as a direct toolbar item.

Properties

Update via update_ticker_item

{
  ticker: "AAPL",
  text: "AAPL $186.25 ▲",
  styles: {color: "#22c55e"},
  class_add: "stock-up",
  class_remove: "stock-down"
}

Example

# Build ticker items
items = [
    build_ticker_item(ticker="AAPL", text="AAPL $185.50"),
    build_ticker_item(ticker="GOOGL", text="GOOGL $142.20"),
]

# Use in marquee
marquee_text = " • ".join(items)

Toolbar Container Structure

All components go inside the toolbars array. Each toolbar has:

Complete Example

{
  "html": "<div id=\"content\">Main content here</div>",
  "title": "My Widget",
  "height": 600,
  "toolbars": [
    {
      "position": "top",
      "items": [
        {"type": "button", "label": "Save", "event": "file:save", "variant": "primary"},
        {"type": "button", "label": "Cancel", "event": "file:cancel", "variant": "secondary"},
        {"type": "select", "event": "file:format", "options": [
          {"label": "JSON", "value": "json"},
          {"label": "CSV", "value": "csv"}
        ], "selected": "json"}
      ]
    },
    {
      "position": "bottom",
      "items": [
        {"type": "div", "content": "Status: Ready", "component_id": "status"},
        {"type": "slider", "event": "zoom:level", "value": 100, "min": 50, "max": 200, "label": "Zoom:"}
      ]
    }
  ]
}

Event Format Rules

MANDATORY FORMAT: namespace:action

All events MUST follow this pattern:

• namespace: Starts with letter, alphanumeric only (e.g., form, view, settings)
• action: Starts with letter, can include letters, numbers, underscores, hyphens (e.g., submit, change, api-key)

Valid Examples

✅ form:submit ✅ view:change ✅ settings:api-key ✅ counter:increment ✅ filter:price-range

Invalid Examples

❌ submit (no namespace) ❌ form-submit (hyphen instead of colon) ❌ 123:action (namespace starts with number) ❌ :action (empty namespace) ❌ form: (empty action)

Reserved Namespaces (DO NOT USE)

• pywry - Internal PyWry events
• plotly - Plotly chart events (except plotly:modebar-*)
• grid - AG Grid events

Summary: All Component Types

END OF REFERENCE. USE THESE EXACT STRUCTURES. NO EXCEPTIONS.