Button

A clickable action trigger. Accepts the button text as the first positional argument.

Usage

A button does one thing: it runs an action when activated. Wire that action with on_click= and shape the rest with two independent knobs — accent= for intent (the semantic color) and variant= for weight (how much it stands out). Everything else here is a refinement of those three ideas.

Accent colors

Use accent= to express intent. The button renders correctly across all themes without hard-coding any color.

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

Style variants

Use variant= to control visual weight. Useful for distinguishing primary actions from secondary ones.

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

Note

A ghost or outline button looks right only when it matches the surface it sits on. On a non-default container (a Card, a darker chrome strip, an overlay) pass surface= at construction ('card', 'chrome', 'overlay', …) to match. It is a build-time setting, not a runtime property; a Toolbar sets it for you on the buttons it builds.

Icons

Pass any Bootstrap Icons name to icon=. The icon appears to the left of the text by default.

bs.Button("Save",   icon="save")
bs.Button("Delete", icon="trash",    accent="danger")
bs.Button("Export", icon="download", accent="secondary", variant="outline")

Icon position

Use icon_position= to control where the icon sits relative to the text. Defaults to 'left'.

bs.Button("Left",   icon="arrow-left",  icon_position="left")
bs.Button("Right",  icon="arrow-right", icon_position="right")
bs.Button("Top",    icon="arrow-up",    icon_position="top")
bs.Button("Bottom", icon="arrow-down",  icon_position="bottom")

Icon-only

Omit the text to show only the icon — icon_only is inferred automatically. Pass icon_only=True explicitly when you want to be clear about intent.

# icon_only inferred — no text provided
bs.Button(icon="plus-lg",  accent="success")
bs.Button(icon="dash-lg",  accent="danger")
bs.Button(icon="pencil",   accent="secondary", variant="outline")
bs.Button(icon="trash",    accent="danger",    variant="outline")

# explicit form — equivalent, states intent clearly
bs.Button("Delete", icon="trash", icon_only=True, accent="danger")

Uniform width

Use width= (in character units) to make a row of buttons the same width.

bs.Button("Save",   accent="primary", width=10)
bs.Button("Cancel",                   width=10)
bs.Button("Reset",  accent="danger",  width=10)

Compact density

Use density='compact' to reduce padding — useful in toolbars where space is tight.

bs.Button("Cut",   icon="scissors",  density="compact")
bs.Button("Copy",  icon="copy",      density="compact")
bs.Button("Paste", icon="clipboard", density="compact")

Disabled state

bs.Button("Disabled Solid",   accent="primary",                    disabled=True)
bs.Button("Disabled Outline", accent="primary", variant="outline", disabled=True)

Reactive text

Bind a Signal[str] to textsignal= so the button text updates automatically.

running  = bs.Signal(False)
btn_text = bs.Signal("Start")

running.subscribe(lambda v: btn_text.set("Stop" if v else "Start"))

bs.Button(textsignal=btn_text, accent="primary",
          on_click=lambda: running.set(not running()))

# Or set directly via the .text property
btn = bs.Button("Start", accent="primary")
btn.text = "Stop"

Custom image

For artwork beyond the Bootstrap Icons set — a logo, an embedded resource — pass an Image handle to image=. Reach for icon= for standard glyphs and image= for custom pictures.

from bootstack.images import Image

bs.Button("Open", image=Image.open("logo.png"))

The handle is also a live property — assigning button.image swaps the picture in place. See Picture and the Image reference for the full image API.

Events

A button fires on activation — a mouse release over it, Space/Return while it has keyboard focus, or a programmatic click(). A disabled button never fires on any of those paths. The simplest form is the on_click= constructor callback, which takes no arguments:

bs.Button("Save",   accent="primary", on_click=handle_save)
bs.Button("Cancel", on_click=lambda: print("Cancelled"))

Use the on_click() method when you need a cancellable subscription or want to compose the event as a Stream. Its handler receives the activation Event:

# Cancellable subscription
btn = bs.Button("Save", accent="primary")
sub = btn.on_click(lambda event: handle_save())
sub.cancel()  # unsubscribe

# Composable Stream — e.g. ignore rapid double-clicks
btn.on_click().debounce(300).listen(lambda event: handle_save())

Note

Because keyboard and programmatic activations carry no pointer, treat the event’s position and modifier fields as unset — use on_click= (or ignore the argument) unless you specifically need a mouse-only gesture. See Handling Actions for wiring actions across widgets and Events for the full event model.

Keyboard

• Tab / Shift+Tab — move focus to or from the button.

• Space / Return — activate the focused button, firing the click exactly as a mouse release does. A disabled button is skipped in the focus order.

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

See also

• MenuButton — a button that opens a menu of actions

• ButtonGroup — a row of related buttons sharing one style

• ToggleButton — a button that holds an on/off state

• Handling Actions — wiring actions and shortcuts across widgets

• Events — the event model behind on_click

API

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

Button

A clickable action trigger.

Full Example

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

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

    # Style variants
    bs.Label("Style Variants", font="heading-sm")
    with bs.Row(gap=8):
        bs.Button("Solid",   accent="primary", variant="solid")
        bs.Button("Outline", accent="primary", variant="outline")
        bs.Button("Ghost",   accent="primary", variant="ghost")

    # Icons
    bs.Label("Icons", font="heading-sm")
    with bs.Row(gap=8):
        bs.Button("Save",   icon="save")
        bs.Button("Delete", icon="trash",    accent="danger")
        bs.Button("Export", icon="download", accent="secondary", variant="outline")

    # Icon position
    bs.Label("Icon Position", font="heading-sm")
    with bs.Row(gap=8):
        bs.Button("Left",   icon="arrow-left",  icon_position="left")
        bs.Button("Right",  icon="arrow-right", icon_position="right")
        bs.Button("Top",    icon="arrow-up",    icon_position="top")
        bs.Button("Bottom", icon="arrow-down",  icon_position="bottom")

    # Icon-only (icon_only inferred when no text is provided)
    bs.Label("Icon Only", font="heading-sm")
    with bs.Row(gap=4):
        bs.Button(icon="plus-lg",  accent="success")
        bs.Button(icon="dash-lg",  accent="danger")
        bs.Button(icon="pencil",   accent="secondary", variant="outline")
        bs.Button(icon="trash",    accent="danger",    variant="outline")

    # Uniform width
    bs.Label("Uniform Width", font="heading-sm")
    with bs.Row(gap=8):
        bs.Button("Save",   accent="primary", width=10)
        bs.Button("Cancel",                  width=10)
        bs.Button("Reset",  accent="danger",  width=10)

    # Reactive text via Signal
    bs.Label("Reactive Text", font="heading-sm")
    with bs.Row(gap=8, vertical_items="center"):
        running  = bs.Signal(False)
        btn_text = bs.Signal("Start")
        running.subscribe(lambda v: btn_text.set("Stop" if v else "Start"))
        bs.Button(
            textsignal=btn_text,
            accent="success",
            on_click=lambda: running.set(not running()),
        )
        bs.Label(textsignal=btn_text, accent="secondary")

    # Compact density
    bs.Label("Compact Density", font="heading-sm")
    with bs.Row(gap=4):
        bs.Button("Cut",    icon="scissors",  density="compact")
        bs.Button("Copy",   icon="copy",      density="compact")
        bs.Button("Paste",  icon="clipboard", density="compact")

    # Disabled
    bs.Label("Disabled", font="heading-sm")
    with bs.Row(gap=8):
        bs.Button("Disabled Solid",   accent="primary", disabled=True)
        bs.Button("Disabled Outline", accent="primary", variant="outline", disabled=True)

app.run()