RadioGroup

A group of mutually exclusive radio buttons.

Usage

Basic

Pass a list of strings — the label and value are the same for each option.

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

Use (text, value) tuples — or {"text": ..., "value": ...} dicts — when the display text should differ from the stored value.

size = bs.RadioGroup([("Small", "s"), ("Medium", "m"), ("Large", "l")], value="m")
size.value      # -> "m"        (the selected value)
size.text       # -> "Medium"   (the selected label)
size.selection  # -> {"text": "Medium", "value": "m"}   (the full record)

Options are a data bag — alongside the recognized keys (text, value, and the per-option icon/disabled), any other key you add (e.g. {"text": "Medium", "value": "m", "px": 16}) rides along and is returned by .selection (see Select for details). A per-option icon renders beside that button’s label, and disabled greys out a single option so it can’t be chosen — distinct from the group-level disabled= that locks every button.

Orientation

bs.RadioGroup(["A", "B", "C"], orient="horizontal")  # default
bs.RadioGroup(["A", "B", "C"], orient="vertical")

Accent colors

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

Title

A title= adds a label rendered above the group. title is also a live property — assign to it to change the label later, or set it to None to remove it.

bs.RadioGroup(
    [("Small", "s"), ("Medium", "m"), ("Large", "l")],
    title="Size", value="m",
)
bs.RadioGroup(
    [("Light", "light"), ("Dark", "dark"), ("Auto", "auto")],
    title="Theme", orient="vertical", value="auto",
)

Reactive binding

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

size = bs.Signal("m")

bs.RadioGroup([("Small", "s"), ("Medium", "m"), ("Large", "l")], signal=size)

size.subscribe(lambda v: apply_size(v))

Runtime options

Add, remove, and reconfigure options after construction. configure_item() updates a single option in place — relabel it, or enable/disable just that one. (Toggling the group-level disabled resets every option, so apply per-option states after it.)

group = bs.RadioGroup(["A", "B"])
group.add("C")                        # label and value both "C"
group.add("Delta", value="d")         # separate label and value
group.remove("A")

group.configure_item("d", label="Δ Delta")   # relabel one option
group.configure_item("C", disabled=True)      # disable just this option

"d" in group                          # membership test, by value
len(group)                            # number of options

Disabled

bs.RadioGroup(["Alpha", "Beta", "Gamma"], value="Beta", disabled=True)

Events

group = bs.RadioGroup(["S", "M", "L"])

# Fires whenever the selection changes
group.on_change(lambda e: print("selected:", group.value))

# As a Stream
group.on_change().listen(lambda e: update_preview(group.value))

Programmatic control

group = bs.RadioGroup(["A", "B", "C"], value="A")

group.value = "B"             # select programmatically
group.disabled = True         # lock the group
group.title = "Choose one"    # update the label live

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

RadioGroup

A group of mutually exclusive radio buttons.

Full Example

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

    # Basic
    bs.Label("Basic", font="heading-sm")
    bs.RadioGroup(["Small", "Medium", "Large"], value="Medium")

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

    # Orientation
    bs.Label("Orientation", font="heading-sm")
    with bs.HStack(gap=32):
        bs.RadioGroup(["A", "B", "C"], value="A", title="Horizontal")
        bs.RadioGroup(["A", "B", "C"], value="A", title="Vertical", orient="vertical")

    # With title
    bs.Label("With Title", font="heading-sm")
    with bs.HStack(gap=32):
        bs.RadioGroup(
            [("Small", "s"), ("Medium", "m"), ("Large", "l")], title="Size", value="m",
        )
        bs.RadioGroup(
            [("Light", "light"), ("Dark", "dark"), ("Auto", "auto")],
            title="Theme", orient="vertical", value="auto",
        )

    # Disabled
    bs.Label("Disabled", font="heading-sm")
    bs.RadioGroup(["Alpha", "Beta", "Gamma"], value="Beta", disabled=True)

app.run()