CommandBar

A horizontal strip of buttons, labels, separators, and other widgets. Items are added left-to-right via add_button(), add_label(), add_separator(), add_spacer(), and add_widget().

Usage

Adding buttons

Pass label= for text, icon= for an icon, or both for a text-and-icon button. Omit label= to get an icon-only button.

tb = bs.CommandBar(fill="x")

tb.add_button("Save", icon="floppy")           # text + icon
tb.add_button(icon="gear")                      # icon-only
tb.add_button("Cancel")                         # text-only

Use on_click= to attach a callback, and accent= to apply a color intent to individual buttons.

tb.add_button("Publish", icon="cloud-upload", accent="primary", on_click=publish)
tb.add_button("Discard", icon="trash", accent="danger", on_click=discard)

Separators and spacers

add_separator() inserts a thin vertical rule between item groups. add_spacer() inserts a flexible gap that pushes everything added after it to the right side.

tb.add_button("Bold", icon="type-bold")
tb.add_button("Italic", icon="type-italic")
tb.add_separator()
tb.add_button("Align left", icon="text-left")
tb.add_spacer()
tb.add_button(icon="gear")          # pinned to the right

Labels

add_label() adds non-interactive text, optionally with an icon. Use it for the application name or section titles.

tb.add_label("My App", font="heading-md")
tb.add_separator()
tb.add_button("New", icon="file-earmark-plus")

Density

density="compact" reduces padding and button size — useful for secondary command bars such as a rich-text formatting strip.

tb = bs.CommandBar(fill="x", density="compact")
tb.add_button(icon="type-bold")
tb.add_button(icon="type-italic")
tb.add_button(icon="type-underline")

Button variant

button_variant= sets the default variant for all buttons added to the command bar. Override per-button with the variant= argument on add_button().

tb = bs.CommandBar(fill="x", button_variant="outline")
tb.add_button("Save", icon="floppy")        # outline
tb.add_button("Run", variant="solid")       # override to solid

Border and surface

show_border=True draws a border around the command bar. surface= controls the background token — 'card' lifts it slightly from the page background.

tb = bs.CommandBar(fill="x", show_border=True, surface="card")
tb.add_button("New",  icon="file-earmark-plus")
tb.add_button("Open", icon="folder2-open")
tb.add_button("Save", icon="floppy")

Custom widgets

Use add_widget() to embed any widget (e.g. a Select) in the command bar. Create the widget with the command bar as its parent first.

tb = bs.CommandBar(fill="x")
branch = bs.Select(
    ["main", "dev", "feat/new-ui"],
    parent=tb,
)
tb.add_widget(branch)

Custom titlebar

Set show_window_controls=True to add minimize, maximize, and close buttons on the right, and draggable=True to let the user drag the window by the command bar. Pair with undecorated=True on the App to remove the OS title bar.

with bs.App(title="My App", undecorated=True) as app:
    tb = bs.CommandBar(
        fill="x",
        show_window_controls=True,
        draggable=True,
    )
    tb.add_label("My App", font="heading-md")
    tb.add_spacer()
    ...
app.run()

Command bar inside AppShell

AppShell includes a built-in command bar. Access it via shell.commandbar and call the same add_* methods. Use command= (not on_click=) when calling add_button() on the AppShell command bar.

with bs.AppShell(title="My App") as shell:
    shell.commandbar.add_spacer()
    shell.commandbar.add_button(icon="circle-half", command=bs.toggle_theme)
    ...

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

AppShell — full application scaffold with a built-in command bar, sidebar, and page stack.

Button — standalone button widget.

API

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

CommandBar

A horizontal strip of buttons, labels, and other widgets.

Full Example

with bs.App(title="CommandBar demo", minsize=(700, 300), padding=16) as app:

    with bs.VStack(fill="both", expand=True, gap=16):

        # ── Default density ────────────────────────────────────────────────
        with bs.VStack(fill="x", padding=(16, 12, 16, 4)):
            bs.Label("Default", font="heading-sm")

            tb1 = bs.CommandBar(fill="x")
            tb1.add_label("Editor", font="heading-md")
            tb1.add_separator()
            tb1.add_button("New", icon="file-earmark-plus")
            tb1.add_button("Open", icon="folder2-open")
            tb1.add_button("Save", icon="floppy")
            tb1.add_spacer()
            tb1.add_button(icon="circle-half", on_click=bs.toggle_theme)
            tb1.add_button(icon="gear")

        # ── Compact density ────────────────────────────────────────────────
        with bs.VStack(fill="x", padding=(16, 12, 16, 4)):
            bs.Label("Compact density", font="heading-sm")

            tb2 = bs.CommandBar(fill="x", density="compact")
            tb2.add_button(icon="type-bold")
            tb2.add_button(icon="type-italic")
            tb2.add_button(icon="type-underline")
            tb2.add_separator()
            tb2.add_button(icon="text-left")
            tb2.add_button(icon="text-center")
            tb2.add_button(icon="text-right")
            tb2.add_separator()
            tb2.add_button(icon="list-ul")
            tb2.add_button(icon="list-ol")
            tb2.add_spacer()
            tb2.add_button(icon="arrow-counterclockwise")
            tb2.add_button(icon="arrow-clockwise")

        # ── Accents and variants ───────────────────────────────────────────
        with bs.VStack(fill="x", padding=(16, 12, 16, 4)):
            bs.Label("Accents and variants", font="heading-sm")
            tb3 = bs.CommandBar(fill="x")
            tb3.add_button("Publish", icon="cloud-upload", accent="primary")
            tb3.add_button("Preview", icon="eye")
            tb3.add_button("Draft", icon="pencil")
            tb3.add_spacer()
            tb3.add_button("Discard", icon="trash", accent="danger")

        # ── Border & Surface ────────────────────────────────────────────────
        with bs.VStack(fill="x", padding=(16, 12, 16, 4)):
            bs.Label("Border and Surface", font="heading-sm")

            tb1 = bs.CommandBar(fill="x", show_border=True, surface="card")
            tb1.add_button("New", icon="file-earmark-plus")
            tb1.add_button("Open", icon="folder2-open")
            tb1.add_button("Save", icon="floppy")


app.run()