ButtonGroup

A row (or column) of visually-connected buttons sharing a common accent and variant. Buttons are added one at a time via add().

Usage

Basic usage

Create a group and add buttons with add(). The group handles layout and shared styling automatically.

bg = bs.ButtonGroup()
bg.add("Save")
bg.add("Cancel")
bg.add("Reset")

Accent colors

Set accent= on the group to apply a color intent to every button. Each button inherits the group accent unless you override it individually via **kwargs in add().

bg = bs.ButtonGroup(accent="primary")
bg.add("Save")
bg.add("Cancel")

Style variants

Use variant= to control visual weight across the whole group.

bs.ButtonGroup(accent="primary", variant="solid")    # default
bs.ButtonGroup(accent="primary", variant="outline")
bs.ButtonGroup(accent="primary", variant="ghost")

Icons

Pass icon= to add() to show a Bootstrap Icon alongside the label.

bg = bs.ButtonGroup(accent="primary", variant="outline")
bg.add("Bold",      icon="type-bold")
bg.add("Italic",    icon="type-italic")
bg.add("Underline", icon="type-underline")

Icon-only

Omit the label to show only the icon — icon_only is inferred automatically, same as for Button.

bg = bs.ButtonGroup(variant="outline", accent="primary")
bg.add(icon="type-bold")
bg.add(icon="type-italic")
bg.add(icon="type-underline")
bg.add(icon="type-strikethrough")

Vertical orientation

Pass 'vertical' as the first argument (or orient='vertical') to stack buttons top-to-bottom instead of left-to-right.

bg = bs.ButtonGroup("vertical", accent="primary", variant="outline")
bg.add("Cut",   icon="scissors")
bg.add("Copy",  icon="copy")
bg.add("Paste", icon="clipboard")

Compact density

Use density='compact' to reduce button padding — useful inside toolbars.

bg = bs.ButtonGroup(accent="primary", density="compact")
bg.add("Cut",   icon="scissors")
bg.add("Copy",  icon="copy")
bg.add("Paste", icon="clipboard")

Disabled state

Set disabled=True to make all buttons in the group non-interactive at once. Toggle the disabled property at runtime to re-enable.

bg = bs.ButtonGroup(accent="primary", disabled=True)
bg.add("Save")
bg.add("Cancel")

# Toggle at runtime
bg.disabled = False

Handling clicks

Use on_click() on the group to handle any button press in one place. The handler receives a ButtonGroupClickEvent with key, text, and icon for the clicked button.

bg = bs.ButtonGroup(accent="primary")
bg.add("Save",   icon="save",  key="save")
bg.add("Cancel", icon="x-lg", key="cancel")
bg.add("Delete", icon="trash", key="delete")

def handle_click(e):
    print(e.key, e.text, e.icon)

bg.on_click(handle_click)

# As a subscription (cancellable)
sub = bg.on_click(handle_click)
sub.cancel()

# As a Stream (composable)
bg.on_click().listen(handle_click)

Managing items

add() and add_all() return the key(s) assigned to each button. Keys are auto-generated ('widget_0', 'widget_1', …) unless you provide them explicitly. Use keys with remove(), update_item(), query_item(), and item().

bg = bs.ButtonGroup(accent="primary")

# Add one at a time
bg.add("Save",   icon="save",  key="save")
bg.add("Cancel", icon="x-lg", key="cancel")

# Or all at once
bg.add_all([
    dict(label="Cut",   icon="scissors", key="cut"),
    dict(label="Copy",  icon="copy",     key="copy"),
    dict(label="Paste", icon="clipboard"),
])

# Inspect
print(bg.keys)         # ('save', 'cancel', 'cut', 'copy', 'widget_0')
print(len(bg))         # 5
print("save" in bg)    # True

# Query a button's current value
bg.query_item("save", "text")          # 'Save'

# Reconfigure after creation
bg.update_item("save", text="Saving…", state="disabled")

# Remove a button
bg.remove("cancel")

# Access the underlying button widget
btn = bg.item("save")

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).

See also

• Button — standalone button

• ToggleGroup — button group with selection state tracking

API

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

ButtonGroup

A row (or column) of visually-connected buttons sharing accent and variant.

Full Example

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

    # Accent colors
    bs.Label("Accent Colors", font="heading-sm")
    with bs.HStack(gap=8):
        for accent in ("default", "primary", "secondary", "success", "warning", "danger"):
            bg = bs.ButtonGroup(accent=accent)
            bg.add("A")
            bg.add("B")

    # Style variants
    bs.Label("Style Variants", font="heading-sm")
    with bs.HStack(gap=8):
        for variant in ("solid", "outline", "ghost"):
            bg = bs.ButtonGroup(variant=variant)
            bg.add("Save")
            bg.add("Cancel")

    # Icons
    bs.Label("Icons", font="heading-sm")
    bg = bs.ButtonGroup(accent="primary", variant="outline")
    bg.add("Bold",      icon="type-bold")
    bg.add("Italic",    icon="type-italic")
    bg.add("Underline", icon="type-underline")

    # Icon-only (icon_only inferred when no label is provided)
    bs.Label("Icon Only", font="heading-sm")
    with bs.HStack(gap=8):
        bg1 = bs.ButtonGroup(variant="outline", accent="primary")
        bg1.add(icon="type-bold")
        bg1.add(icon="type-italic")
        bg1.add(icon="type-underline")
        bg1.add(icon="type-strikethrough")

        bg2 = bs.ButtonGroup()
        bg2.add(icon="scissors")
        bg2.add(icon="copy")
        bg2.add(icon="clipboard")

    # Vertical orientation
    bs.Label("Vertical Orientation", font="heading-sm")
    bg = bs.ButtonGroup("vertical", accent="primary", variant="outline")
    bg.add("Cut",   icon="scissors")
    bg.add("Copy",  icon="copy")
    bg.add("Paste", icon="clipboard")

    # Compact density
    bs.Label("Compact Density", font="heading-sm")
    with bs.HStack(gap=8):
        bg1 = bs.ButtonGroup(accent="primary")
        bg1.add("Cut",   icon="scissors")
        bg1.add("Copy",  icon="copy")
        bg1.add("Paste", icon="clipboard")

        bg2 = bs.ButtonGroup(accent="primary", density="compact")
        bg2.add("Cut",   icon="scissors")
        bg2.add("Copy",  icon="copy")
        bg2.add("Paste", icon="clipboard")

    # Disabled
    bs.Label("Disabled", font="heading-sm")
    with bs.HStack(gap=8):
        bg1 = bs.ButtonGroup(accent="primary")
        bg1.add("Save")
        bg1.add("Cancel")

        bg2 = bs.ButtonGroup(accent="primary", disabled=True)
        bg2.add("Save")
        bg2.add("Cancel")

    # Handling clicks (group-level on_click — e.data has key, text, icon)
    bs.Label("Handling Clicks", font="heading-sm")
    bg = bs.ButtonGroup(accent="primary")
    bg.add("Save",   icon="save",  key="save")
    bg.add("Cancel", icon="x-lg", key="cancel")
    bg.add("Delete", icon="trash", key="delete")
    last = bs.Signal("(none)")
    bg.on_click(lambda e: last.set(e.key))
    bs.Label(textsignal=last, accent="secondary")

app.run()