SubmenuButton

A menu button that displays a cascading menu.

Typically used in a MenuBar control.

ft.SubmenuButton(
    content=ft.Text("Choose text style"),
    key="smbutton",
    expand=True,
    menu_style=ft.MenuStyle(
        alignment=ft.Alignment.BOTTOM_LEFT, side=ft.BorderSide(1)
    ),
    controls=[
        ft.MenuItemButton(
            content=ft.Text("Underlined"),
            on_click=lambda e: print(f"{e.control.content.value}.on_click"),
        ),
        ft.MenuItemButton(...),
        ...,
    ],
)

Activated submenu button

Inherits: LayoutControl

Properties

• alignment_offset - The offset of the menu relative to the alignment origin determined by flet.MenuStyle.alignment on the style attribute.
• clip_behavior - Whether to clip the content of this control or not.
• content - The child control to be displayed in the middle portion of this button.
• controls - A list of controls that appear in the menu when it is opened.
• leading - An optional control to display before the content.
• menu_style - Customizes this menu's appearance.
• style - Customizes this button's appearance.
• trailing - An optional control to display after the content.

Events

• on_blur - Called when this button loses focus.
• on_close - Called when the menu is closed.
• on_focus - Called when the button receives focus.
• on_hover - Called when the button is hovered.
• on_open - Called when the menu is opened.

Examples

Live example

Basic Example

import flet as ft


def main(page: ft.Page):
    page.padding = 0
    page.spacing = 0

    def handle_color_click(e: ft.Event[ft.MenuItemButton]):
        color = e.control.content.value
        background_container.content.value = f"{color} background color"
        background_container.bgcolor = color.lower()

    def handle_alignment_click(e: ft.Event[ft.MenuItemButton]):
        background_container.alignment = e.control.data

    def handle_on_hover(e: ft.Event[ft.MenuItemButton]):
        print(f"{e.control.content.value}.on_hover")

    menubar = ft.MenuBar(
        expand=True,
        controls=[
            ft.SubmenuButton(
                content=ft.Text("Change Body"),
                key="submenubutton",
                controls=[
                    ft.SubmenuButton(
                        content=ft.Text("BG Color"),
                        leading=ft.Icon(ft.Icons.COLORIZE),
                        controls=[
                            ft.MenuItemButton(
                                content=ft.Text("Blue"),
                                on_click=handle_color_click,
                                on_hover=handle_on_hover,
                                style=ft.ButtonStyle(
                                    bgcolor={ft.ControlState.HOVERED: ft.Colors.BLUE}
                                ),
                            ),
                            ft.MenuItemButton(
                                content=ft.Text("Green"),
                                on_click=handle_color_click,
                                on_hover=handle_on_hover,
                                style=ft.ButtonStyle(
                                    bgcolor={ft.ControlState.HOVERED: ft.Colors.GREEN}
                                ),
                            ),
                            ft.MenuItemButton(
                                content=ft.Text("Red"),
                                on_click=handle_color_click,
                                on_hover=handle_on_hover,
                                style=ft.ButtonStyle(
                                    bgcolor={ft.ControlState.HOVERED: ft.Colors.RED}
                                ),
                            ),
                        ],
                    ),
                    ft.SubmenuButton(
                        content=ft.Text("Text alignment"),
                        leading=ft.Icon(ft.Icons.LOCATION_PIN),
                        controls=[
                            ft.MenuItemButton(
                                content=ft.Text("bottom_center"),
                                data=ft.Alignment.BOTTOM_CENTER,
                                on_click=handle_alignment_click,
                                style=ft.ButtonStyle(
                                    bgcolor={
                                        ft.ControlState.HOVERED: ft.Colors.GREY_100
                                    }
                                ),
                            ),
                            ft.MenuItemButton(
                                content=ft.Text("bottom_left"),
                                data=ft.Alignment.BOTTOM_LEFT,
                                on_click=handle_alignment_click,
                                style=ft.ButtonStyle(
                                    bgcolor={
                                        ft.ControlState.HOVERED: ft.Colors.GREY_100
                                    }
                                ),
                            ),
                            ft.MenuItemButton(
                                content=ft.Text("top_center"),
                                data=ft.Alignment.TOP_CENTER,
                                on_click=handle_alignment_click,
                                style=ft.ButtonStyle(
                                    bgcolor={
                                        ft.ControlState.HOVERED: ft.Colors.GREY_100
                                    }
                                ),
                            ),
                            ft.MenuItemButton(
                                content=ft.Text("center_left"),
                                data=ft.Alignment.CENTER_LEFT,
                                on_click=handle_alignment_click,
                                style=ft.ButtonStyle(
                                    bgcolor={
                                        ft.ControlState.HOVERED: ft.Colors.GREY_100
                                    }
                                ),
                            ),
                            ft.MenuItemButton(
                                content=ft.Text("center_right"),
                                data=ft.Alignment.CENTER_RIGHT,
                                on_click=handle_alignment_click,
                                style=ft.ButtonStyle(
                                    bgcolor={
                                        ft.ControlState.HOVERED: ft.Colors.GREY_100
                                    }
                                ),
                            ),
                        ],
                    ),
                ],
            )
        ],
    )

    page.add(
        ft.SafeArea(
            expand=True,
            content=ft.Column(
                expand=True,
                spacing=0,
                controls=[
                    ft.Row(controls=[menubar]),
                    background_container := ft.Container(
                        expand=True,
                        bgcolor=ft.Colors.SURFACE_TINT,
                        alignment=ft.Alignment.CENTER,
                        content=ft.Text(
                            value="Choose a bgcolor from the menu",
                            style=ft.TextStyle(size=24, weight=ft.FontWeight.BOLD),
                        ),
                    ),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Properties

buildalignment_offsetclass-attributeinstance-attribute

alignment_offset: Optional[OffsetValue] = None

The offset of the menu relative to the alignment origin determined by flet.MenuStyle.alignment on the style attribute.

buildclip_behaviorclass-attributeinstance-attribute

clip_behavior: ClipBehavior = ClipBehavior.HARD_EDGE

Whether to clip the content of this control or not.

buildcontentclass-attributeinstance-attribute

content: Optional[StrOrControl] = None

The child control to be displayed in the middle portion of this button.

Typically this is the button's label, using a Text control.

buildcontrolsclass-attributeinstance-attribute

controls: list[Control] = field(default_factory=list)

A list of controls that appear in the menu when it is opened.

Typically either MenuItemButton or SubMenuButton controls.

If this list is empty, then the button for this menu item will be disabled.

buildleadingclass-attributeinstance-attribute

leading: Optional[Control] = None

An optional control to display before the content.

Typically an Icon control.

buildmenu_styleclass-attributeinstance-attribute

menu_style: Optional[MenuStyle] = None

Customizes this menu's appearance.

buildstyleclass-attributeinstance-attribute

style: Optional[ButtonStyle] = None

Customizes this button's appearance.

buildtrailingclass-attributeinstance-attribute

trailing: Optional[Control] = None

An optional control to display after the content.

Typically an Icon control.

Events

bolton_blurclass-attributeinstance-attribute

on_blur: Optional[ControlEventHandler[SubmenuButton]] = None

Called when this button loses focus.

bolton_closeclass-attributeinstance-attribute

on_close: Optional[ControlEventHandler[SubmenuButton]] = None

Called when the menu is closed.

bolton_focusclass-attributeinstance-attribute

on_focus: Optional[ControlEventHandler[SubmenuButton]] = None

Called when the button receives focus.

bolton_hoverclass-attributeinstance-attribute

on_hover: Optional[ControlEventHandler[SubmenuButton]] = None

Called when the button is hovered.

bolton_openclass-attributeinstance-attribute

on_open: Optional[ControlEventHandler[SubmenuButton]] = None

Called when the menu is opened.