SelectButton

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

Usage

A select button is a single-choice value picker styled as a button that shows the current selection — like a Select without the editable text field. .value is the chosen option’s value, and on_change fires on change.

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"],   value="Solid",   accent="primary", variant="solid")
bs.SelectButton(["Outline"], value="Outline", accent="primary", variant="outline")
bs.SelectButton(["Ghost"],   value="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 with signal=. The button and signal stay in sync, and the signal carries the selected option’s value — not the label shown for it, which matters when the two differ. When signal= is provided, value= is ignored — seed the Signal with an option’s value.

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 — Column / Row parents use the layout kwargs below, grid-based parents use grid kwargs.

Column (vertical layout)

Used inside a Column, App, or any other container with a column layout. Children are arranged top-to-bottom, so horizontal aligns each child across the width and grow shares the vertical space. (vertical does not apply — the order of the children sets their top-to-bottom position.)

horizontal	Cross-axis placement of the widget: 'left', 'center', 'right', or 'stretch' to fill the available width.
grow	Claim and fill a share of the leftover vertical space (the layout direction). True or False.
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=.

Row (horizontal layout)

Used inside a Row or any other container with a row layout. Children are arranged left-to-right, so vertical aligns each child across the height and grow shares the horizontal space. (horizontal does not apply — the order of the children sets their left-to-right position.)

vertical	Cross-axis placement of the widget: 'top', 'center', 'bottom', or 'stretch' to fill the available height.
grow	Claim and fill a share of the leftover horizontal space (the layout direction). True or False.
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.
horizontal	Horizontal placement within the grid cell: 'left', 'center', 'right', or 'stretch' to fill the cell width.
vertical	Vertical placement within the grid cell: 'top', 'center', 'bottom', or 'stretch' to fill the cell height.
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.Row(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.Row(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.Row(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.Row(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.Row(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()