SelectButton

A button that opens a dropdown value list and displays the current selection.

Usage

Basic

Pass a list of options. The button displays the currently selected value.

bs.SelectButton(["Light", "Dark", "Auto"], value="Light")

Option values

Like Select, an option’s label can differ from its value — pass a (text, value) tuple or a {"text": ..., "value": ...} dict. value=, .value, and the change event are in value-space.

mode = bs.SelectButton([("Light theme", "light"), ("Dark theme", "dark")], value="dark")
mode.value             # -> "dark"          (the value)
mode.text              # -> "Dark theme"    (the displayed label)
mode.selection         # -> {"text": "Dark theme", "value": "dark"}   (the full record)
mode.on_change(lambda e: apply_theme(e.value))

Options are a data bag — alongside the recognized keys (text, value, and the per-option icon/disabled), any other key you add rides along and is returned by .selection (see Select for details). A per-option icon renders beside that menu item’s label, and disabled greys out a single option so it can’t be chosen — distinct from the widget-level disabled= that locks the whole control.

Accent colors

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

Style variants

bs.SelectButton(["Solid"],   accent="primary", variant="solid")
bs.SelectButton(["Outline"], accent="primary", variant="outline")
bs.SelectButton(["Ghost"],   accent="primary", variant="ghost")

With icon

bs.SelectButton(["Light", "Dark", "Auto"],
                value="Dark", icon="moon-fill")
bs.SelectButton(["Small", "Medium", "Large"],
                value="Large", icon="fonts", accent="secondary")

Reactive binding

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

theme = bs.Signal("light")
bs.SelectButton(["Light", "Dark", "Auto"], signal=theme)
theme.subscribe(lambda v: bs.set_theme(v.lower()))

Disabled

bs.SelectButton(["A", "B", "C"], value="B", disabled=True)
bs.SelectButton(["A", "B", "C"], value="B", disabled=True,
                accent="primary", variant="outline")

Events

btn = bs.SelectButton(["Small", "Medium", "Large"], value="Medium")

btn.on_change(lambda e: print("selected:", btn.value))

# As a Stream
btn.on_change().listen(lambda e: apply_size(btn.value))

Programmatic control

btn = bs.SelectButton(["A", "B", "C"], value="A")

btn.value = "C"                 # change selection
btn.disabled = True             # lock the button
btn.options = ["X", "Y", "Z"]   # replace the choice list (rebuilds the dropdown)

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 SelectButton lives on the Widgets API page. At a glance:

SelectButton

A button that opens a dropdown value list — a button-styled alternative to Select.

Full Example

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

    # Basic
    bs.Label("Basic", font="heading-sm")
    with bs.HStack(gap=8):
        bs.SelectButton(["Light", "Dark", "Auto"], value="Light")
        bs.SelectButton(["Small", "Medium", "Large"], value="Medium")

    # Accent colors
    bs.Label("Accent Colors", font="heading-sm")
    with bs.HStack(gap=8):
        for accent in ("primary", "secondary", "info", "success", "warning", "danger"):
            bs.SelectButton(["On", "Off"], value="On", accent=accent)

    # Style variants
    bs.Label("Style Variants", font="heading-sm")
    with bs.HStack(gap=8):
        for variant in ("solid", "outline", "ghost"):
            bs.SelectButton(["A", "B", "C"], value="A",
                            accent="primary", variant=variant)

    # With icon
    bs.Label("With Icon", font="heading-sm")
    with bs.HStack(gap=8):
        bs.SelectButton(["Light", "Dark", "Auto"],
                        value="Dark", icon="moon-fill")
        bs.SelectButton(["Small", "Medium", "Large"],
                        value="Large", icon="fonts", accent="secondary")

    # Disabled
    bs.Label("Disabled", font="heading-sm")
    with bs.HStack(gap=8):
        bs.SelectButton(["A", "B", "C"], value="B", disabled=True)
        bs.SelectButton(["A", "B", "C"], value="B", disabled=True,
                        accent="primary", variant="outline")

app.run()