pywry.modal

Modal dialog definitions and HTML generation.

---

pywry.modal.Modal

Bases: BaseModel

A modal overlay container with input components.

Attributes:

Name	Type	Description
component_id	str	Unique identifier for this modal (auto-generated if not provided).
title	str	Modal header title.
items	list	List of input items (Button, Select, TextInput, Div, etc.).
size	str	Preset size ("sm", "md", "lg", "xl", "full").
width	str	Custom width override (e.g., "600px").
max_height	str	Maximum height before scrolling (default: "80vh").
overlay_opacity	float	Background overlay opacity 0.0-1.0 (default: 0.5).
close_on_escape	bool	Close when Escape key pressed (default: True).
close_on_overlay_click	bool	Close when clicking outside modal (default: True).
reset_on_close	bool	Reset form inputs when closed (default: True).
on_close_event	str	Custom event name to emit when modal closes.
open_on_load	bool	Whether modal starts open (default: False).
style	str	Inline CSS for the modal container.
script	str	JS file path or inline string to inject.
class_name	str	Custom CSS class for the modal container.

Examples:

>>> Modal(
...     title="User Settings",
...     size="md",
...     class_name="settings-modal",
...     items=[
...         TextInput(label="Username", event="user:name"),
...         Toggle(label="Notifications", event="user:notifications"),
...         Button(label="Save", event="user:save", variant="primary"),
...     ],
...     reset_on_close=False,
...     on_close_event="settings:closed",
... )

Functions

normalize_items classmethod

normalize_items(v: Any) -> list[ToolbarItem]

Accept list of dicts or ToolbarItem objects.

build_html

build_html() -> str

Build complete modal HTML.

Returns:

Type	Description
str	The modal HTML structure with overlay, container, header, and body.

collect_scripts

collect_scripts() -> list[str]

Collect scripts from modal and all nested Div children.

Modal script runs first, then Div scripts in item order.

Returns:

Type	Description
list[str]	List of script content strings.

to_dict

to_dict() -> dict[str, Any]

Convert modal to dict for state/serialization.

Returns:

Type	Description
dict	Modal configuration as a dictionary.

get_secret_inputs

get_secret_inputs() -> list[SecretInput]

Get all SecretInput items in this modal (including nested in Divs).

Returns:

Type	Description
list[SecretInput]	All SecretInput components found.

pywry.modal.get_modal_script

get_modal_script() -> str

Get the modal initialization script.

This script is injected once per page to enable modal functionality.

Returns:

Type	Description
str	Complete modal script wrapped in script tags.

pywry.modal.wrap_content_with_modals

wrap_content_with_modals(_content: str, modals: Sequence[Modal | dict[str, Any]] | None) -> tuple[str, str]

Build modal HTML and scripts to inject into page.

Parameters:

Name	Type	Description	Default
_content	str	The main page content (unused, kept for API symmetry with toolbars).	required
modals	Sequence[Modal | dict] | None	List of Modal objects or dicts to render.	required

Returns:

Type	Description
tuple[str, str]	A tuple of (modal_html, modal_scripts) to inject into the page.