Toolbar

The container that holds and organizes UI components. Toolbars can be positioned around your content.

Basic Usage

from pywry import PyWry, Toolbar, Button, Select, Option

app = PyWry()

toolbar = Toolbar(
    position="top",
    items=[
        Button(label="Save", event="file:save"),
        Select(
            label="Theme",
            event="settings:theme",
            options=[
                Option(label="Light", value="light"),
                Option(label="Dark", value="dark"),
            ],
        ),
    ],
)

app.show("<h1>My App</h1>", toolbars=[toolbar])

Positions

Toolbars can be placed in 7 different positions:

Toolbar(position="top", items=[...])      # Horizontal, above content
Toolbar(position="bottom", items=[...])   # Horizontal, below content
Toolbar(position="left", items=[...])     # Vertical, left side
Toolbar(position="right", items=[...])    # Vertical, right side
Toolbar(position="header", items=[...])   # Fixed at very top
Toolbar(position="footer", items=[...])   # Fixed at very bottom
Toolbar(position="inside", items=[...])   # Overlays content

Layout Hierarchy

HEADER

LEFT

TOP

CONTENT

INSIDE

BOTTOM

RIGHT

FOOTER

Multiple Toolbars

Use multiple toolbars for complex layouts:

from pywry import PyWry, Toolbar, Button, Div

app = PyWry()

app.show(
    "<h1>Dashboard</h1>",
    toolbars=[
        Toolbar(
            position="header",
            items=[Button(label="☰ Menu", event="nav:menu")],
        ),
        Toolbar(
            position="top",
            items=[
                Button(label="Save", event="file:save"),
                Button(label="Export", event="file:export"),
            ],
        ),
        Toolbar(
            position="left",
            items=[
                Button(label="📊 Charts", event="view:charts"),
                Button(label="📋 Tables", event="view:tables"),
            ],
        ),
        Toolbar(
            position="footer",
            items=[Div(content="Status: Ready")],
        ),
    ],
)

Component Mix

Combine different components in a toolbar:

toolbar = Toolbar(
    position="top",
    items=[
        # Actions
        Button(label="💾 Save", event="file:save", variant="primary"),

        # Selection
        Select(
            label="View",
            event="view:mode",
            options=[
                Option(label="Grid", value="grid"),
                Option(label="List", value="list"),
            ],
        ),

        # Input
        SearchInput(
            label="Search",
            event="data:search",
            placeholder="Search items...",
        ),

        # Display
        Div(content="<span class='status'>●</span> Connected"),

        # Toggle
        Toggle(label="Auto-refresh", event="settings:autorefresh"),
    ],
)

Vertical Toolbars

Left and right toolbars render components vertically:

side_nav = Toolbar(
    position="left",
    items=[
        Button(label="🏠", event="nav:home"),      # Icon buttons work well
        Button(label="📊", event="nav:analytics"),
        Button(label="⚙️", event="nav:settings"),
    ],
)

Styling

Toolbars automatically inherit theme styles. For custom styling, use CSS:

/* In your custom CSS */
.pywry-toolbar-top {
    background: linear-gradient(to right, #667eea, #764ba2);
}

.pywry-toolbar-left {
    border-right: 2px solid var(--pywry-border-color);
}

API Reference

Bases: BaseModel

A toolbar container with positioned items.

Attributes:

Name	Type	Description
component_id	str	Unique identifier for this toolbar (auto-generated if not provided).
position	str	Where to place the toolbar: "top", "bottom", "left", "right", or "inside".
items	list	List of toolbar items (Button, Select, TextInput, Div, etc.).
style	str	Optional inline CSS for the toolbar container.
script	str or Path or None	JS file path or inline string to inject into the toolbar.
class_name	str	Custom CSS class added to the toolbar container.
collapsible	bool	Enable collapse/expand behavior with toggle button.
resizable	bool	Enable drag-to-resize on toolbar edge (direction based on position).

Examples:

>>> Toolbar(
...     position="top",
...     class_name="my-toolbar",
...     collapsible=True,
...     resizable=True,
...     items=[
...         Button(label="Refresh", event="app:refresh"),
...         Select(label="View:", event="view:change", options=[...]),
...         Div(content="<span>Custom</span>", class_name="custom-section"),
...     ],
... )

Methods:

normalize_items classmethod

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

Accept list of dicts or ToolbarItem objects.

build_html

build_html() -> str

Build complete toolbar HTML with collapsible/resizable support.

collect_scripts

collect_scripts() -> list[str]

Collect scripts from toolbar and all nested Div children (depth-first).

Toolbar 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 toolbar to dict.

get_secret_inputs

get_secret_inputs() -> list[SecretInput]

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

Returns:

Type	Description
list[SecretInput]	All SecretInput components found.

register_secrets

register_secrets() -> None

Register all SecretInput values in the secret registry.

Called automatically when rendering. Ensures secrets are available for reveal/copy handlers.

get_secret_events

get_secret_events() -> list[tuple[str, str, str]]

Get all secret-related events that need handlers.

Returns:

Type	Description
list[tuple[str, str, str]]	List of (component_id, reveal_event, copy_event) tuples.