OptionMenu

Bases: MenuButton

A single-selection dropdown menu backed by a ContextMenu.

Renders as a MenuButton with a chevron icon. Clicking the button opens a popup menu containing the provided options as radiobutton items. Selecting an item updates the displayed text and fires a <<Change>> event.

Events

<<Change>>: Fired when the selected value changes. event.data = {'value': Any}

value `property` `writable`

value: str

Get or set the current value.

init

__init__(
    master: Master = None,
    value: Any = None,
    options: list[Any] = None,
    **kwargs: Unpack[OptionMenuKwargs],
)

Create an OptionMenu backed by a ContextMenu.

Events

<<Change>>: Fired when the selected value changes. event.data = {'value': Any}

Parameters:

Name	Type	Description	Default
`master`	`Master`	Parent widget. If None, uses the default root window.	`None`
`value`	`Any`	Initial selected value.	`None`
`options`	`list`	List of values to populate the menu.	`None`

Other Parameters:

Name	Type	Description
`command`	`Callable`	Callback invoked when the value changes via menu selection.
`image`	`PhotoImage`	Tk image to display.
`icon`	`str \| dict`	Bootstyle icon spec for the label content.
`icon_only`	`bool`	Whether to reserve label padding when showing only an icon.
`compound`	`str`	Placement of image relative to text.
`padding`	`int \| tuple`	Extra padding around the menubutton content.
`width`	`int`	Width of the menubutton.
`underline`	`int`	Index of underlined character in text.
`state`	`str`	Widget state ('normal', 'active', 'disabled', 'readonly').
`takefocus`	`bool`	Participation in focus traversal.
`style`	`str`	Explicit ttk style name (overrides accent/variant).
`textvariable`	`Variable`	Existing Tk variable to bind; new StringVar created if omitted.
`textsignal`	`Signal[str]`	Signal bound to the textvariable.
`accent`	`str`	Accent token for styling, e.g. 'primary', 'danger', 'success'.
`variant`	`str`	Style variant, e.g. 'solid', 'outline'.
`bootstyle`	`str`	DEPRECATED - Use `accent` and `variant` instead. Combined style tokens (e.g., 'primary-outline').
`surface`	`str`	Surface token for style.
`style_options`	`dict`	Dict forwarded to the style builder (e.g., icon_only, surface).
`show_dropdown_button`	`bool`	Toggle visibility of the dropdown chevron.
`dropdown_button_icon`	`str \| dict`	Icon name for the chevron; defaults to 'caret-down-fill'.

show_menu

show_menu()

Show the dropdown menu unless disabled or readonly.

get

get() -> str

Return the current value.

set

set(value: Any) -> None

Set the current value (coerced to string).

on_changed

on_changed(callback: Callable) -> str

Bind to <<Change>>. Callback receives event.data = {'value': Any}.

off_changed

off_changed(bind_id: str | None = None) -> None

Unbind from <<Change>>.