Skip to content

ContextMenu

ContextMenu is a widget-backed pop-up menu for right-click and contextual actions.

Unlike Tk’s native Menu, it is composed of bootstack widgets. This makes it fully themeable (light/dark), enables icons, and allows richer layout and interaction patterns.

Quick start

Create a menu, add items, and show it in response to a right-click.

import bootstack as bs

app = bs.App()

menu = bs.ContextMenu(app)
menu.add_command(text="Open", icon="folder-open", command=lambda: print("Open"))
menu.add_command(text="Rename", command=lambda: print("Rename"))
menu.add_separator()
menu.add_command(text="Delete", icon="trash", command=lambda: print("Delete"))

def on_right_click(event):
    menu.show((event.x_root, event.y_root))

app.bind("<Button-3>", on_right_click)
app.mainloop()

When to use

Use ContextMenu when:

  • actions are contextual to a widget, list row, or region
  • you want theme-consistent menus across platforms
  • you want icons or richer item styling

Consider a different control when…

  • you want a native OS menu → use Tk’s Menu via MenuButton
  • you want a button-first action with a small menu → use DropdownButton

Command items

Use command items for standard actions.

menu.add_command(text="Open", command=on_open)

Check items

Use check items for independent on/off options.

menu.add_checkbutton(text="Show hidden files", value=True)
menu.add_checkbutton(text="Pin to sidebar", value=False)

Radio items

Use radio items for selecting one option from a set.

sort_var = bs.StringVar(value="name")
menu.add_radiobutton(text="Sort by name", value="name", variable=sort_var)
menu.add_radiobutton(text="Sort by date", value="date", variable=sort_var)

Behavior

  • show(position) displays the menu at a screen coordinate (x, y).
  • hide() programmatically closes the menu.
  • The menu hides automatically when the user clicks outside.
  • Item commands fire on click and close the menu.

See State & Interaction for focus, hover, and disabled behavior across widgets.

See Virtual Events for interaction events emitted by bootstack widgets.

Icons

Menu items use the same icon system as other bootstack widgets.

menu.add_command(text="Settings", icon="gear", command=on_settings)

See Icons & Imagery for icon sizing, DPI handling, and recoloring behavior.

Localization

If localization is enabled, menu item labels can be message tokens.

menu.add_command(text="menu.open", command=on_open)
menu.add_command(text="menu.delete", command=on_delete)

See Localization for how message tokens are resolved and language switching works.

Positioning patterns

Attach to a target widget

menu = bs.ContextMenu(
    app,
    target=my_button,
    anchor="nw",
    attach="se",
    offset=(5, 5)
)
menu.show()

Show at pointer location

menu.show((event.x_root, event.y_root))

Advanced patterns

Dynamic menus

Build context-sensitive menus by creating a new menu or conditionally adding items.

def on_right_click(event):
    menu = bs.ContextMenu(root)
    menu.add_command(text="Open", command=on_open)
    if can_delete():
        menu.add_command(text="Delete", command=on_delete)
    menu.show((event.x_root, event.y_root))

Centralized item handling

Register a single callback to route menu actions.

def on_item_click(info):
    print(info["text"], info["value"])

menu.on_item_click(on_item_click)

See API Reference → ContextMenu for full item management and callback APIs.

Additional resources

Framework concepts

API reference