Checkbox

A checkable box for boolean selections, typically used in forms.

Checked Unchecked

Basic Usage

from pywry import Checkbox

agree = Checkbox(
    label="I agree to the terms",
    event="form:agree",
    value=False,
)

Common Patterns

Form Agreement

from pywry import PyWry, Toolbar, Checkbox, Button

app = PyWry()

def on_agree_change(data, event_type, label):
    agreed = data["value"]
    # Enable/disable submit button based on agreement
    app.emit("toolbar:set-value", {
        "componentId": "submit-btn",
        "disabled": not agreed
    }, label)

def on_submit(data, event_type, label):
    app.emit("pywry:alert", {"message": "Form submitted!", "type": "success"}, label)

app.show(
    "<h1>Sign Up</h1><p>Please agree to continue.</p>",
    toolbars=[
        Toolbar(position="bottom", items=[
            Checkbox(label="I agree to the terms and conditions", event="form:agree"),
            Button(
                component_id="submit-btn",
                label="Submit",
                event="form:submit",
                variant="primary",
                disabled=True,  # Initially disabled
            ),
        ])
    ],
    callbacks={
        "form:agree": on_agree_change,
        "form:submit": on_submit,
    },
)

Multiple Checkboxes

from pywry import Toolbar, Checkbox, Div

features_toolbar = Toolbar(
    position="right",
    items=[
        Div(content="<strong>Features</strong>"),
        Checkbox(label="Email notifications", event="pref:email", value=True),
        Checkbox(label="SMS notifications", event="pref:sms", value=False),
        Checkbox(label="Push notifications", event="pref:push", value=True),
    ],
)

Select All Pattern

from pywry import PyWry, Toolbar, Checkbox

app = PyWry()
items = [{"id": 1, "name": "Item A"}, {"id": 2, "name": "Item B"}, {"id": 3, "name": "Item C"}]

def on_select_all(data, event_type, label):
    select_all = data["value"]
    # Update all child checkboxes
    for item in items:
        app.emit("toolbar:set-value", {
            "componentId": f"item-{item['id']}",
            "value": select_all
        }, label)

def on_item_select(data, event_type, label):
    app.emit("pywry:alert", {
        "message": f"Item selected: {data.get('value')}",
        "type": "info"
    }, label)

app.show(
    "<h1>Select Items</h1>",
    toolbars=[
        Toolbar(position="top", items=[
            Checkbox(label="Select All", event="items:select_all"),
            *[Checkbox(
                component_id=f"item-{item['id']}",
                label=item['name'],
                event="item:select"
            ) for item in items],
        ])
    ],
    callbacks={
        "items:select_all": on_select_all,
        "item:select": on_item_select,
    },
)

Attributes

component_id : str | None
    Unique identifier for state tracking (auto-generated if not provided)
label : str | None
    Display label shown next to the checkbox
description : str | None
    Tooltip/hover text for accessibility and user guidance
event : str
    Event name emitted on interaction (format: namespace:event-name)
style : str | None
    Optional inline CSS
disabled : bool
    Whether the checkbox is disabled (default: False)
value : bool
    Current checked state (default: False)

Events

Emits the event name with payload:

{"value": true, "componentId": "checkbox-abc123"}

• value — true when checked, false when unchecked

Checkbox vs Toggle

Component	Visual	Use Case
Checkbox	Checkmark box	Forms, multiple selections, agreements
Toggle	Switch	Settings that apply immediately

API Reference

Bases: ToolbarItem

A single checkbox for boolean values.

Emits {value: ..., componentId: ...} on check/uncheck.

Attributes:

Name	Type	Description
value	bool	Initial checked state (default: False).

Examples:

>>> Checkbox(label="Enable notifications", event="settings:notify", value=True)

Functions

build_html

build_html() -> str

Build checkbox HTML.

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.