ToggleButton

A button that stays pressed when active — command-bar-style toggle.

Usage

Basic

bs.ToggleButton("Inactive", value=False)
bs.ToggleButton("Active",   value=True)

Accent colors

bs.ToggleButton("Primary",   accent="primary",   value=True)
bs.ToggleButton("Secondary", accent="secondary", value=True)
bs.ToggleButton("Info",      accent="info",      value=True)
bs.ToggleButton("Success",   accent="success",   value=True)
bs.ToggleButton("Warning",   accent="warning",   value=True)
bs.ToggleButton("Danger",    accent="danger",    value=True)

Style variants

Use variant= to control visual weight. Each variant is shown inactive then active so the state change is visible.

bs.ToggleButton("Solid off",   accent="primary", variant="solid",   value=False)
bs.ToggleButton("Solid on",    accent="primary", variant="solid",   value=True)
bs.ToggleButton("Outline off", accent="primary", variant="outline", value=False)
bs.ToggleButton("Outline on",  accent="primary", variant="outline", value=True)
bs.ToggleButton("Ghost off",   accent="primary", variant="ghost",   value=False)
bs.ToggleButton("Ghost on",    accent="primary", variant="ghost",   value=True)

State icons

Use on_icon= and off_icon= to display different icons for each state. Either argument can be used alone — on_icon= alone swaps the icon on activation without needing a separate inactive icon.

bs.ToggleButton("Favorite", on_icon="star-fill", off_icon="star",
                accent="warning", value=True)
bs.ToggleButton("Favorite", on_icon="star-fill", off_icon="star",
                accent="warning", value=False)
bs.ToggleButton("Pin", on_icon="pin-fill", off_icon="pin",
                accent="primary", value=True)
bs.ToggleButton("Pin", on_icon="pin-fill", off_icon="pin",
                accent="primary", value=False)

Icon only

Set icon_only=True to show just the icon with no label text. Useful for compact command bars.

bs.ToggleButton(on_icon="star-fill",  off_icon="star",  accent="warning", value=True,  icon_only=True)
bs.ToggleButton(on_icon="star-fill",  off_icon="star",  accent="warning", value=False, icon_only=True)
bs.ToggleButton(on_icon="pin-fill",   off_icon="pin",   accent="primary", value=True,  icon_only=True)
bs.ToggleButton(on_icon="heart-fill", off_icon="heart", accent="danger",  value=True,  icon_only=True)
bs.ToggleButton(on_icon="heart-fill", off_icon="heart", accent="danger",  value=False, icon_only=True)

Compact density

bs.ToggleButton("Compact", density="compact", value=False)
bs.ToggleButton("Compact", density="compact", value=True, accent="primary")
bs.ToggleButton(on_icon="star-fill", off_icon="star",
                density="compact", accent="warning", value=True, icon_only=True)

Reactive binding

Bind a Signal with signal=. The button and signal stay in sync. When signal= is provided, value= is ignored — seed the Signal directly.

bold = bs.Signal(False)
bs.ToggleButton("Bold", signal=bold, on_icon="type-bold")
bold.subscribe(lambda v: apply_bold(v))

Disabled

bs.ToggleButton("Disabled inactive", disabled=True, value=False)
bs.ToggleButton("Disabled active",   disabled=True, value=True)

Events

btn = bs.ToggleButton("Option")

# Fires on every toggle
btn.on_change(lambda e: print("active:", btn.checked))

# Fires only when pressed/activated
btn.on_check(lambda e: print("activated"))

# Fires only when released/deactivated
btn.on_uncheck(lambda e: print("deactivated"))

# As a Stream
btn.on_change().debounce(200).listen(lambda e: save())

Programmatic control

btn = bs.ToggleButton("Option")

btn.checked = True     # activate
btn.value              # → True
btn.toggle()           # flip state

btn.disabled = True    # lock the button

Widget sizing

All widgets accept self-placement kwargs via **kwargs. The parent container determines which options apply — stack-based parents use stack kwargs, grid-based parents use grid kwargs. Unrecognised keys are silently ignored.

Stack

Used inside VStack, HStack, App, and other stack containers.

fill	Fill direction: 'x', 'y', 'both', or 'none'.
expand	Grow to consume extra space in the parent. True or False.
anchor	Alignment when the widget does not fill the available slot: 'n', 's', 'e', 'w', 'center', 'nw', etc.
margin	External spacing in pixels. Accepts an integer (equal on all sides), a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing (left and right). Accepts an integer or a 2-tuple (left, right) for asymmetric spacing. Overrides the horizontal component of margin=.
margin_y	Vertical external spacing (top and bottom). Accepts an integer or a 2-tuple (top, bottom) for asymmetric spacing. Overrides the vertical component of margin=.

Grid

Used inside a Grid container.

row / column	Zero-based row and column indices.
rowspan / columnspan	Number of rows or columns to span.
sticky	Alignment and fill within the grid cell. Any combination of 'n', 's', 'e', 'w' — e.g. 'ew' stretches horizontally, 'nsew' fills the entire cell.
margin	External spacing in pixels. Accepts an integer, a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing. Accepts an integer or (left, right).
margin_y	Vertical external spacing. Accepts an integer or (top, bottom).

API

The complete reference for ToggleButton lives on the Widgets API page. At a glance:

ToggleButton

A button that stays pressed when active — toolbar-style toggle.

Full Example

with bs.App(title="ToggleButton Demo", padding=20, gap=16) as app:

    # Basic
    bs.Label("Basic", font="heading-sm")
    with bs.HStack(gap=8):
        bs.ToggleButton("Inactive", value=False)
        bs.ToggleButton("Active",   value=True)

    # Accent colors
    bs.Label("Accent Colors", font="heading-sm")
    with bs.HStack(gap=8):
        for accent in ("default", "primary", "secondary", "info", "success", "warning", "danger"):
            bs.ToggleButton(accent.title(), accent=accent, value=True)

    # Style variants
    bs.Label("Style Variants", font="heading-sm")
    with bs.HStack(gap=16):
        for variant in ("solid", "outline", "ghost"):
            with bs.VStack(gap=4):
                bs.ToggleButton(f"{variant.title()} — off", accent="primary", variant=variant, value=False)
                bs.ToggleButton(f"{variant.title()} — on",  accent="primary", variant=variant, value=True)

    # State icons
    bs.Label("State Icons", font="heading-sm")
    with bs.HStack(gap=8):
        bs.ToggleButton("Favorite",
            on_icon="star-fill", off_icon="star",
            accent="warning", value=True)
        bs.ToggleButton("Favorite",
            on_icon="star-fill", off_icon="star",
            accent="warning", value=False)
        bs.ToggleButton("Pin",
            on_icon="pin-fill", off_icon="pin",
            accent="primary", value=True)
        bs.ToggleButton("Pin",
            on_icon="pin-fill", off_icon="pin",
            accent="primary", value=False)

    # Icon only
    bs.Label("Icon Only", font="heading-sm")
    with bs.HStack(gap=8):
        bs.ToggleButton(on_icon="star-fill",  off_icon="star",   accent="warning", value=True,  icon_only=True)
        bs.ToggleButton(on_icon="star-fill",  off_icon="star",   accent="warning", value=False, icon_only=True)
        bs.ToggleButton(on_icon="pin-fill",   off_icon="pin",    accent="primary", value=True,  icon_only=True)
        bs.ToggleButton(on_icon="heart-fill", off_icon="heart",  accent="danger",  value=True,  icon_only=True)
        bs.ToggleButton(on_icon="heart-fill", off_icon="heart",  accent="danger",  value=False, icon_only=True)

    # Compact density
    bs.Label("Compact Density", font="heading-sm")
    with bs.HStack(gap=8):
        bs.ToggleButton("Compact",  density="compact", value=False)
        bs.ToggleButton("Compact",  density="compact", value=True, accent="primary")
        bs.ToggleButton(on_icon="star-fill", off_icon="star", density="compact",
                        accent="warning", value=True, icon_only=True)

    # Disabled
    bs.Label("Disabled", font="heading-sm")
    with bs.HStack(gap=8):
        bs.ToggleButton("Disabled inactive", disabled=True, value=False)
        bs.ToggleButton("Disabled active",   disabled=True, value=True)

app.run()