Select¶

Dropdown for single-choice selection.

Theme:

Searchable¶

Country:

Select(
    label="Country",
    event="form:country",
    options=[
        Option(label="United States", value="us"),
        Option(label="United Kingdom", value="uk"),
        Option(label="Canada", value="ca"),
        Option(label="Germany", value="de"),
        Option(label="France", value="fr"),
        Option(label="Japan", value="jp"),
    ],
    selected="us",
    searchable=True,
)

Complete Example¶

from pywry import PyWry, Toolbar, Select, Option

app = PyWry()

def on_theme(data, event_type, label):
    app.emit("pywry:update-theme", {"theme": data["value"]}, label)
    app.emit("pywry:alert", {"message": f"Theme: {data['value']}", "type": "info"}, label)

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

app.show("<h1>Settings</h1>", toolbars=[toolbar], callbacks={"settings:theme": on_theme})
app.block()

Dynamic Options¶

Update dropdown options based on another selection:

from pywry import PyWry, Toolbar, Select, Option

app = PyWry()

categories = {
    "fruits": ["Apple", "Banana", "Orange"],
    "vegetables": ["Carrot", "Broccoli", "Spinach"],
}

def on_category(data, event_type, label):
    items = categories.get(data["value"], [])
    app.emit("toolbar:set-value", {
        "componentId": "item-select",
        "options": [{"label": i, "value": i.lower()} for i in items],
        "value": items[0].lower() if items else None,
    }, label)

def on_item(data, event_type, label):
    app.emit("pywry:alert", {"message": f"Selected: {data['value']}"}, label)

toolbar = Toolbar(
    position="top",
    items=[
        Select(
            label="Category",
            event="form:category",
            options=[Option(label="Fruits", value="fruits"), Option(label="Vegetables", value="vegetables")],
            selected="fruits",
        ),
        Select(
            component_id="item-select",
            label="Item",
            event="form:item",
            options=[Option(label="Apple", value="apple"), Option(label="Banana", value="banana"), Option(label="Orange", value="orange")],
            selected="apple",
        ),
    ],
)

app.show("<h1>Selection</h1>", toolbars=[toolbar], callbacks={"form:category": on_category, "form:item": on_item})
app.block()

Attributes¶

component_id : str | None
    Unique identifier for state tracking (auto-generated if not provided)
label : str | None
    Display label shown next to the dropdown
description : str | None
    Tooltip/hover text for accessibility and user guidance
event : str
    Event name emitted on selection change (format: namespace:event-name)
style : str | None
    Optional inline CSS
disabled : bool
    Whether the dropdown is disabled (default: False)
options : list[Option]
    List of Option(label, value) items
selected : str
    Currently selected value (default: "")
searchable : bool
    Enable a search input to filter dropdown options (default: False)

Events¶

Emits the event name with payload:

{"value": "dark", "componentId": "select-abc123"}

value — the value string of the selected option

API Reference¶

Bases: ToolbarItem

A single-select dropdown with optional search.

Emits {value: ..., componentId: ...} on selection change.

Attributes:

Name	Type	Description
`options`	`list of Option`	List of Option items for the dropdown.
`selected`	`str`	Currently selected value.
`searchable`	`bool`	Enable search input to filter options (default: False).

Examples:

>>> Select(
...     label="Theme:",
...     event="theme:change",
...     options=[
...         Option(label="Dark", value="dark"),
...         Option(label="Light", value="light"),
...     ],
...     selected="dark",
...     searchable=True,
... )

normalize_options `classmethod` ¶

normalize_options(v: Any) -> list[Option]

Accept list of dicts or Option objects.

build_html ¶

build_html() -> str

Build custom dropdown HTML (not native select, for consistent styling).

auto_generate_component_id ¶

auto_generate_component_id() -> ToolbarItem

Auto-generate component_id based on type if not provided.

validate_event_name `classmethod` ¶

validate_event_name(v: str) -> str

Validate event follows namespace:event-name pattern.