PyWry

Modals - MANDATORY PATTERN

STOP. READ THIS ENTIRE FILE BEFORE CREATING MODALS.

Overview

Modals are reusable overlay dialogs that can contain any content - forms, confirmations, information panels, or custom HTML. They follow the same pattern as toolbars, passed to .show-* functions.

The ONLY Correct Way to Create Modals

Copy this EXACTLY. Do not deviate.

from pywry import Modal, show_plotly

fig = go.Figure(...)

widget = show_plotly(
    fig,
    modals=[
        Modal(
            component_id="settings-modal",
            title="Settings",
            items=["<p>Configure your preferences here.</p>"],
            size="medium",
        )
    ],
    toolbars=[{
        "position": "top",
        "items": [
            {"type": "button", "label": "Open Settings", "event": "modal:open:settings-modal"}
        ]
    }]
)

THAT'S IT. Button click opens the modal automatically.

Modal Schema

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | component_id | str | YES | - | Unique identifier for the modal | | title | str | no | "" | Modal header title | | items | list[str] | no | [] | HTML content strings | | size | str | no | "medium" | "small", "medium", "large", "fullscreen" | | width | str | no | None | Custom width (e.g., "600px", "80%") | | max_height | str | no | None | Custom max-height (e.g., "400px") | | overlay_opacity | float | no | 0.5 | Backdrop opacity (0.0-1.0) | | close_on_escape | bool | no | True | Close when Escape key pressed | | close_on_overlay_click | bool | no | True | Close when clicking outside modal | | reset_on_close | bool | no | True | Reset form inputs when closed | | on_close_event | str | no | None | Event to emit when modal closes | | open_on_load | bool | no | False | Open modal immediately on page load | | style | str | no | "" | Additional CSS for this modal | | script | str | no | "" | Additional JavaScript for this modal | | class_name | str | no | "" | Additional CSS classes |

Size Presets

| Size | Width | Use Case | |------|-------|----------| | small | 320px | Confirmations, alerts | | medium | 500px | Forms, settings (default) | | large | 720px | Complex forms, tables | | fullscreen | 95vw / 95vh | Data grids, large content |

Modal Events

These are the ONLY events that work with modals:

Opening and Closing

| Event Type | Description | |------------|-------------| | modal:open:<component_id> | Opens the modal | | modal:close:<component_id> | Closes the modal | | modal:toggle:<component_id> | Toggles open/closed state |

Example: Button to Open Modal

toolbars=[{
    "position": "top",
    "items": [
        {"type": "button", "label": "Settings", "event": "modal:open:settings-modal"}
    ]
}]

Example: Button Inside Modal to Close

Modal(
    component_id="confirm-modal",
    title="Confirm Action",
    items=[
        "<p>Are you sure?</p>",
        '<button onclick="window.pywry.modal.close(\'confirm-modal\')">Cancel</button>',
        '<button onclick="doAction()">Confirm</button>',
    ]
)

Built-in Close Behaviors

1. X Button: Every modal has a close button in the top-right corner
2. Escape Key: Press Escape to close (unless close_on_escape=False)
3. Overlay Click: Click outside modal to close (unless close_on_overlay_click=False)

reset_on_close Behavior

When reset_on_close=True (default):

• All <input>, <textarea>, <select> elements are reset to their initial values
• Form state is cleared when modal closes
• Next open shows fresh form

When reset_on_close=False:

• Form values persist between opens
• User can resume where they left off

JavaScript API

Access modal functions via window.pywry.modal:

// Open a modal
window.pywry.modal.open('my-modal');

// Close a modal  
window.pywry.modal.close('my-modal');

// Toggle a modal
window.pywry.modal.toggle('my-modal');

// Check if modal is open
const isOpen = window.pywry.modal.isOpen('my-modal');

Complete Examples

1. Settings Modal with Form

from pywry import Modal, show_plotly

widget = show_plotly(
    fig,
    modals=[
        Modal(
            component_id="settings",
            title="Chart Settings",
            items=[
                '<form id="settings-form">',
                '  <label>Title: <input type="text" name="title" value="My Chart"></label>',
                '  <label>Theme: <select name="theme">',
                '    <option value="dark">Dark</option>',
                '    <option value="light">Light</option>',
                '  </select></label>',
                '  <button type="button" onclick="applySettings()">Apply</button>',
                '</form>',
            ],
            size="medium",
            reset_on_close=False,  # Keep form values
        )
    ],
    toolbars=[{
        "position": "top",
        "items": [
            {"type": "button", "label": "⚙️ Settings", "event": "modal:open:settings"}
        ]
    }]
)

2. Confirmation Dialog

Modal(
    component_id="delete-confirm",
    title="Delete Item",
    items=[
        '<p>Are you sure you want to delete this item?</p>',
        '<p style="color: var(--pywry-text-danger);">This action cannot be undone.</p>',
        '<div class="pywry-modal-footer">',
        '  <button onclick="window.pywry.modal.close(\'delete-confirm\')">Cancel</button>',
        '  <button onclick="confirmDelete()" class="danger">Delete</button>',
        '</div>',
    ],
    size="small",
    close_on_overlay_click=False,  # Force user to click a button
)

3. Modal with Custom Styling

Modal(
    component_id="custom-modal",
    title="Styled Modal",
    items=["<p>Custom styled content</p>"],
    style="""
        #custom-modal .pywry-modal-container {
            border: 2px solid var(--pywry-accent);
            border-radius: 16px;
        }
        #custom-modal .pywry-modal-header {
            background: linear-gradient(90deg, var(--pywry-accent), var(--pywry-bg-secondary));
        }
    """,
)

4. Modal with Custom JavaScript

Modal(
    component_id="data-modal",
    title="Data Preview",
    items=['<div id="data-preview"></div>'],
    script="""
        // Populate data when modal opens
        document.getElementById('data-modal').addEventListener('modal:opened', () => {
            fetch('/api/data')
                .then(r => r.json())
                .then(data => {
                    document.getElementById('data-preview').textContent = JSON.stringify(data, null, 2);
                });
        });
    """,
)

CSS Selectors for Styling

Target modal elements with these selectors:

| Selector | Element | |----------|---------| | #<component_id> | The modal overlay | | #<component_id> .pywry-modal-container | The modal box | | #<component_id> .pywry-modal-header | Header with title and close button | | #<component_id> .pywry-modal-title | Title text | | #<component_id> .pywry-modal-close | X close button | | #<component_id> .pywry-modal-body | Content area | | #<component_id> .pywry-modal-footer | Footer area (if you add one) |

Theme Awareness

Modals automatically inherit the current theme:

• .pywry-theme-dark → Dark background, light text
• .pywry-theme-light → Light background, dark text
• .pywry-theme-system → Follows OS preference

Use CSS variables for consistent theming:

.pywry-modal-container {
    background: var(--pywry-bg-secondary);
    color: var(--pywry-text-primary);
    border: 1px solid var(--pywry-border);
}

Common Mistakes

❌ Wrong: event: "open-modal" (missing modal: prefix and component_id) ❌ Wrong: event: "modal:open" (missing component_id) ❌ Wrong