Skip to content

OptionMenu

OptionMenu is a selection control that lets users pick one value from a short list using a menu-style dropdown.

In bootstack v2, OptionMenu wraps Tkinter's bs.Menubutton and adds theming, icons, signals, and standardized change events. It is best suited for compact, known option sets.

Use OptionMenu when the list is small and users already know the available choices. For longer lists or search/filtering, prefer SelectBox.

Overview

OptionMenu provides:

  • single selection (one committed value)

  • menu-based dropdown behavior

  • compact desktop-friendly appearance

  • optional signals and <<Changed>> events

It is intentionally simpler than SelectBox and does not support search or custom values.

Basic usage

import bootstack as bs

app = bs.App()

menu = bs.OptionMenu(
    app,
    value="Medium",
    options=["Low", "Medium", "High"],
)
menu.pack(padx=20, pady=20)

app.mainloop()

Variants

OptionMenu does not have behavioral variants. Its primary variations are visual, controlled by accent and variant (see Colors and styling).

How the value works

  • options defines the list of valid values

  • value is the currently selected option

When the user selects a menu item, OptionMenu updates value and emits <<Changed>>.

print(menu.value)
menu.value = "High"

Binding to signals or variables

You can bind selection state in several ways.

Using a Tk variable

color = bs.StringVar(value="Green")

menu = bs.OptionMenu(
    app,
    textvariable=color,
    options=["Red", "Green", "Blue"],
)

Using a signal

selected = bs.Signal("Medium")

menu = bs.OptionMenu(
    app,
    textsignal=selected,
    options=["Low", "Medium", "High"],
)

selected.subscribe(lambda v: print("changed:", v))

Common options

options

Defines the available choices.

menu.configure(options=["Apple", "Banana", "Cherry"])

value

Set or update the selected value.

menu.configure(value="Banana")

state

Disable or enable the menu.

menu.configure(state="disabled")
menu.configure(state="normal")

width and padding

bs.OptionMenu(
    app,
    value="A",
    options=["A", "B"],
    width=20,
    padding=(10, 6),
).pack(pady=6)

Behavior

  • Clicking the button opens a menu of options.

  • Selecting an item immediately commits the value.

  • The menu closes automatically after selection.

  • Keyboard navigation follows standard ttk menubutton behavior.

Events

OptionMenu emits a committed change event when selection changes.

def on_changed(event):
    print("Selected:", event.data["value"])

menu.on_changed(on_changed)

To unbind:

bind_id = menu.on_changed(on_changed)
menu.off_changed(bind_id)

Validation and constraints

Selection is constrained to options.

Validation is typically unnecessary, but may be useful when:

  • a selection is required before submission

  • options are updated dynamically

Colors and styling

OptionMenu supports the same accent and variant options as MenuButton.

bs.OptionMenu(app, value="A", options=["A", "B"], accent="primary")
bs.OptionMenu(app, value="A", options=["A", "B"], accent="primary", variant="outline")
bs.OptionMenu(app, value="A", options=["A", "B"], accent="primary", variant="ghost")
bs.OptionMenu(app, value="A", options=["A", "B"], variant="text")

Icons

Use icon=... to attach a theme-aware icon.

bs.OptionMenu(
    app,
    value="Dark",
    options=["Light", "Dark", "Auto"],
    icon="palette",
)

Using image=

Passing a Tk PhotoImage via image= will not automatically recolor on theme changes.

Localization

Text shown by OptionMenu participates in localization according to your global widget settings. When localize="auto", untranslated keys fall back to literal text.

When should I use OptionMenu?

Use OptionMenu when:

  • the option list is short (3-15 items)

  • the control should remain compact

  • search or rich presentation is unnecessary

Prefer SelectBox when:

  • the list is long

  • search or filtering is needed

  • users may enter custom values

Prefer RadioButton / RadioGroup when:

  • there are very few options and showing them inline improves clarity

Additional resources

API reference