MenuButton#

A button that opens a dropdown menu when clicked.

Usage#

Basic#

Pass a label= for button text and use add_item() to populate the menu. Items can have an icon= and an on_click= callback.

mb = bs.MenuButton("Actions")
mb.add_item("Edit",      icon="pencil",  on_click=edit)
mb.add_item("Duplicate", icon="copy",    on_click=duplicate)
mb.add_item("Archive",   icon="archive", on_click=archive)
mb.add_separator()
mb.add_item("Delete",    icon="trash",   on_click=delete)

Checkbox and radio items#

add_check_item() adds a toggle item; add_radio_item() adds a mutually exclusive choice item. Both return the item key that can be used with update_item() later.

mb = bs.MenuButton("View", icon="eye")
mb.add_check_item("Show toolbar",   value=True)
mb.add_check_item("Show sidebar",   value=True)
mb.add_check_item("Show status bar")

mb2 = bs.MenuButton("Zoom")
mb2.add_radio_item("100%", value=100)
mb2.add_radio_item("150%", value=150, selected=True)
mb2.add_radio_item("200%", value=200)

MenuButton check and radio items — light theme

MenuButton check and radio items — dark theme

Global item callback#

Pass on_select= to register a single callback for every item click. The callback receives a dict with type, text, and value keys.

def on_action(event):
    print("selected:", event["text"], "→", event["value"])

mb = bs.MenuButton("Actions", on_select=on_action)
mb.add_item("Delete", value="delete")
mb.add_item("Archive", value="archive")

Keyboard shortcuts#

Pass shortcut= to display a key hint on the right side of an item. This is a display label only — it does not bind a keyboard handler. Three forms are accepted:

Modifier pattern — "Mod+S", "Mod+Shift+N", "F5" — translated to the platform-correct string automatically ("Ctrl+S" on Windows, "⌘S" on macOS). No registration required.
Registered key — a name previously passed to get_shortcuts().register() (e.g. "save"). Resolved via the Shortcuts service.
Literal string — anything else is shown as-is (e.g. "Ctrl+S").

Keyboard bindings must be set up separately via the Shortcuts service. Shortcuts are most useful when MenuButton is used in a menubar context:

mb = bs.MenuButton("File", icon="folder2")
mb.add_item("New",  icon="file-earmark-plus",  shortcut="Mod+N", on_click=new_file)
mb.add_item("Open", icon="folder2-open",       shortcut="Mod+O", on_click=open_file)
mb.add_item("Save", icon="floppy",             shortcut="Mod+S", on_click=save_file)
mb.add_separator()
mb.add_item("Exit", icon="box-arrow-right", on_click=app.quit)

MenuButton keyboard shortcuts — light theme

MenuButton keyboard shortcuts — dark theme

Icon button#

Omit label= to get an icon-only button — icon_only is inferred automatically when icon= is set and no label is provided. Set show_arrow=False to hide the chevron.

bs.MenuButton(icon="three-dots",          show_arrow=False)
bs.MenuButton(icon="three-dots-vertical", show_arrow=False)
bs.MenuButton(icon="grid",                show_arrow=False)
bs.MenuButton(icon="gear",                show_arrow=False)

Accent colors#

Use accent= to apply a color intent to the button face.

bs.MenuButton("Primary",   accent="primary")
bs.MenuButton("Secondary", accent="secondary")
bs.MenuButton("Success",   accent="success")
bs.MenuButton("Warning",   accent="warning")
bs.MenuButton("Danger",    accent="danger")

Style variants#

variant= controls the visual weight of the button. 'ghost' (default) blends into the background; 'outline' adds a border; 'solid' fills the button with the accent color.

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

Disabled state#

Set disabled=True to prevent the button from being clicked. The menu will not open while the button is disabled. The disabled property can also be toggled after construction.

mb_a = bs.MenuButton("Enabled")
mb_b = bs.MenuButton("Disabled", disabled=True)
mb_c = bs.MenuButton("Disabled", accent="primary", variant="outline", disabled=True)

mb_b.disabled = False   # re-enable later

Dynamic item management#

Items can be added, updated, or removed at any time after construction.

mb = bs.MenuButton("Actions")
key = mb.add_item("Archive")

mb.update_item(key, disabled=True)   # grey out the item
mb.remove_item(key)                  # remove it entirely

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

MenuButton