Menu

See also

Material Design spec, Menus

Menus display a list of choices on temporary surfaces.

• Menus should be easy to open, close, and interact with

• Menu content should be suited to user needs

• Menu items should be easy to scan

Usage

Declarative Python style with KVDeclarative Python style

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        id: button
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.menu_open()

        MDButtonText:
            text: "Press me"
'''


class Example(MDApp):
    def menu_open(self):
        menu_items = [
            {
                "text": f"Item {i}",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        MDDropdownMenu(
            caller=self.root.ids.button, items=menu_items
        ).open()

    def menu_callback(self, text_item):
        print(text_item)

    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()

Anatomy

You can combine the following parameters:

• leading_icon

• text

• trailing_icon

• trailing_text

…to create the necessary types of menu items:

menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
        "trailing_icon": "apple-keyboard-command",
        "trailing_text": "+Shift+X",
    }
]

menu_items = [
    {
        "text": "Strikethrough",
        "trailing_icon": "apple-keyboard-command",
        "trailing_text": "+Shift+X",
    }
]

menu_items = [
    {
        "text": "Strikethrough",
        "trailing_icon": "apple-keyboard-command",
    }
]

menu_items = [
    {
        "text": "Strikethrough",
        "trailing_text": "Shift+X",
    }
]

menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
        "trailing_icon": "apple-keyboard-command",
    }
]

menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
    }
]

menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
        "trailing_text": "Shift+X",
    }
]

menu_items = [
    {
        "text": "Strikethrough",
    }
]

You can use the following parameters to customize the menu items:

• text_color

• leading_icon_color

• trailing_icon_color

• trailing_text_color

menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
        "trailing_icon": "apple-keyboard-command",
        "trailing_text": "+Shift+X",
        "leading_icon_color": "orange",
        "trailing_icon_color": "green",
        "trailing_text_color": "red",
    }
]

Header

Declarative Python style with KVDeclarative python style

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu
from kivymd.uix.boxlayout import MDBoxLayout

KV = '''
<MenuHeader>
    spacing: "12dp"
    padding: "4dp"
    adaptive_height: True

    MDIconButton:
        icon: "gesture-tap-button"
        pos_hint: {"center_y": .5}

    MDLabel:
        text: "Actions"
        adaptive_size: True
        pos_hint: {"center_y": .5}


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        id: button
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.menu.open()

        MDButtonText:
            text: "Press me"
'''


class MenuHeader(MDBoxLayout):
    '''An instance of the class that will be added to the menu header.'''


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)
        menu_items = [
            {
                "text": f"Item {i}",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        self.menu = MDDropdownMenu(
            header_cls=MenuHeader(),
            caller=self.screen.ids.button,
            items=menu_items,
        )

    def menu_callback(self, text_item):
        print(text_item)

    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Dark"
        return self.screen


Example().run()

Menu with MDTopAppBar

The MDDropdownMenu works well with the standard MDTopAppBar. Since the buttons on the Toolbar are created by the MDTopAppBar component, it is necessary to pass the button as an argument to the callback using lambda x: app.callback(x). This example uses drop down menus for both the righthand and lefthand menus.

Declarative Python style with KVDeclarative python style

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu
from kivymd.uix.snackbar import MDSnackbar, MDSnackbarText

KV = '''
MDBoxLayout:
    orientation: "vertical"
    md_bg_color: self.theme_cls.backgroundColor

    MDTopAppBar:

        MDTopAppBarLeadingButtonContainer:

            MDActionTopAppBarButton:
                icon: "menu"
                on_release: app.callback(self)

        MDTopAppBarTitle:
            text: "MDTopAppBar"
            pos_hint: {"center_x": .5}

        MDTopAppBarTrailingButtonContainer:

            MDActionTopAppBarButton:
                icon: "dots-vertical"
                on_release: app.callback(self)

    MDLabel:
        text: "Content"
        halign: "center"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Dark"
        menu_items = [
            {
                "text": f"Item {i}",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        self.menu = MDDropdownMenu(items=menu_items)
        return Builder.load_string(KV)

    def callback(self, button):
        self.menu.caller = button
        self.menu.open()

    def menu_callback(self, text_item):
        self.menu.dismiss()
        MDSnackbar(
            MDSnackbarText(
                text=text_item,
            ),
            y=dp(24),
            pos_hint={"center_x": 0.5},
            size_hint_x=0.5,
        ).open()


Example().run()

Position

Bottom position

See also

position

Declarative Python style with KVDeclarative Python style

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDTextField:
        id: field
        pos_hint: {'center_x': .5, 'center_y': .6}
        size_hint_x: None
        width: "200dp"
        on_focus: if self.focus: app.menu.open()

        MDTextFieldHintText:
            text: "Password"
'''


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)
        menu_items = [
            {
                "text": f"Item {i}",
                "on_release": lambda x=f"Item {i}": self.set_item(x),
            } for i in range(5)]
        self.menu = MDDropdownMenu(
            caller=self.screen.ids.field,
            items=menu_items,
            position="bottom",
        )

    def set_item(self, text_item):
        self.screen.ids.field.text = text_item
        self.menu.dismiss()

    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Dark"
        return self.screen


Example().run()

Center position

Declarative Python style with KVDeclarative Python style

from kivy.lang import Builder

from kivymd.uix.menu import MDDropdownMenu
from kivymd.app import MDApp

KV = '''
MDScreen
    md_bg_color: self.theme_cls.backgroundColor

    MDDropDownItem:
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.open_drop_item_menu(self)

        MDDropDownItemText:
            id: drop_text
            text: "Item"
'''


class Example(MDApp):
    drop_item_menu: MDDropdownMenu = None

    def open_drop_item_menu(self, item):
        menu_items = [
            {
                "text": f"{i}",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        if not self.drop_item_menu:
            self.drop_item_menu = MDDropdownMenu(
                caller=item, items=menu_items, position="center"
            )
            self.drop_item_menu.open()

    def menu_callback(self, text_item):
        self.root.ids.drop_text.text = text_item
        self.drop_item_menu.dismiss()

    def build(self):
        return Builder.load_string(KV)


Example().run()

API break

1.1.1 version

from kivy.lang import Builder
from kivy.metrics import dp
from kivy.properties import StringProperty

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.list import IRightBodyTouch, OneLineAvatarIconListItem
from kivymd.uix.menu import MDDropdownMenu

KV = '''
<RightContentCls>
    disabled: True
    adaptive_size: True
    pos_hint: {"center_y": .5}

    MDIconButton:
        icon: root.icon
        icon_size: "16sp"
        md_bg_color_disabled: 0, 0, 0, 0

    MDLabel:
        text: root.text
        font_style: "Caption"
        adaptive_size: True
        pos_hint: {"center_y": .5}


<Item>

    IconLeftWidget:
        icon: root.left_icon

    RightContentCls:
        id: container
        icon: root.right_icon
        text: root.right_text


MDScreen:

    MDRaisedButton:
        id: button
        text: "PRESS ME"
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.menu.open()
'''


class RightContentCls(IRightBodyTouch, MDBoxLayout):
    icon = StringProperty()
    text = StringProperty()


class Item(OneLineAvatarIconListItem):
    left_icon = StringProperty()
    right_icon = StringProperty()
    right_text = StringProperty()


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)
        menu_items = [
            {
                "text": f"Item {i}",
                "right_text": "+Shift+X",
                "right_icon": "apple-keyboard-command",
                "left_icon": "web",
                "viewclass": "Item",
                "height": dp(54),
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        self.menu = MDDropdownMenu(
            caller=self.screen.ids.button,
            items=menu_items,
            bg_color="#bdc6b0",
            width_mult=4,
        )

    def menu_callback(self, text_item):
        print(text_item)

    def build(self):
        return self.screen


Example().run()

1.2.0 version

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu

KV = '''
MDScreen:

    MDRaisedButton:
        id: button
        text: "PRESS ME"
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.menu.open()
'''


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)
        menu_items = [
            {
                "text": f"Item {i}",
                "leading_icon": "web",
                "trailing_icon": "apple-keyboard-command",
                "trailing_text": "+Shift+X",
                "trailing_icon_color": "grey",
                "trailing_text_color": "grey",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        self.menu = MDDropdownMenu(
            md_bg_color="#bdc6b0",
            caller=self.screen.ids.button,
            items=menu_items,
        )

    def menu_callback(self, text_item):
        print(text_item)

    def build(self):
        return self.screen


Example().run()

2.0.0 version

Declarative Python style with KVDeclarative Python style

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        id: button
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.menu_open()

        MDButtonText:
            text: "Press me"
'''


class Example(MDApp):
    def menu_open(self):
        menu_items = [
            {
                "text": f"Item {i}",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        MDDropdownMenu(
            caller=self.root.ids.button, items=menu_items
        ).open()

    def menu_callback(self, text_item):
        print(text_item)

    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()

API - kivymd.uix.menu.menu

class kivymd.uix.menu.menu.BaseDropdownItem(**kwargs)

Base class for menu items.

Added in version 1.2.0.

For more information, see in the RectangularRippleBehavior and MDBoxLayout classes.

text

The text of the menu item.

text is a StringProperty and defaults to ‘’.

leading_icon

The leading icon of the menu item.

leading_icon is a StringProperty and defaults to ‘’.

trailing_icon

The trailing icon of the menu item.

trailing_icon is a StringProperty and defaults to ‘’.

trailing_text

The trailing text of the menu item.

trailing_text is a StringProperty and defaults to ‘’.

text_color

The color of the text in (r, g, b, a) or string format for the text of the menu item.

text_color is a ColorProperty and defaults to None.

leading_icon_color

The color of the text in (r, g, b, a) or string format for the leading icon of the menu item.

leading_icon_color is a ColorProperty and defaults to None.

trailing_icon_color

The color of the text in (r, g, b, a) or string format for the trailing icon of the menu item.

leading_icon_color is a ColorProperty and defaults to None.

trailing_text_color

The color of the text in (r, g, b, a) or string format for the trailing text of the menu item.

leading_icon_color is a ColorProperty and defaults to None.

divider

Divider mode. Available options are: ‘Full’, None and default to ‘Full’.

divider is a OptionProperty and defaults to ‘Full’.

divider_color

Divider color in (r, g, b, a) or string format.

divider_color is a ColorProperty and defaults to None.

class kivymd.uix.menu.menu.MDDropdownTextItem(**kwargs)

Implements a menu item with text without leading and trailing icons.

Added in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownLeadingIconItem(**kwargs)

Implements a menu item with text, leading icon and without trailing icon.

Added in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownTrailingIconItem(**kwargs)

Implements a menu item with text, without leading icon and with trailing icon.

Added in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownTrailingIconTextItem(**kwargs)

Implements a menu item with text, without leading icon, with trailing icon and with trailing text.

Added in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownTrailingTextItem(**kwargs)

Implements a menu item with text, without leading icon, without trailing icon and with trailing text.

Added in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownLeadingIconTrailingTextItem(**kwargs)

Implements a menu item with text, leading icon and with trailing text.

Added in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownLeadingTrailingIconTextItem(**kwargs)

Implements a menu item with text, with leading icon, with trailing icon and with trailing text.

Added in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownMenu(**kwargs)

Dropdown menu class.

For more information, see in the MotionDropDownMenuBehavior and StencilBehavior and MDCard classes documentation.

Events:

on_release

The method that will be called when you click menu items.

header_cls

An instance of the class (Kivy or KivyMD widget) that will be added to the menu header.

Added in version 0.104.2.

See Header for more information.

header_cls is a ObjectProperty and defaults to None.

items

List of dictionaries with properties for menu items.

items is a ListProperty and defaults to [].

width_mult

This number multiplied by the standard increment (‘56dp’ on mobile, ‘64dp’ on desktop), determines the width of the menu items.

If the resulting number were to be too big for the application Window, the multiplier will be adjusted for the biggest possible one.

Deprecated since version 1.2.0: Use width instead.

self.menu = MDDropdownMenu(
    width=dp(240),
    ...,
)

width_mult is a NumericProperty and defaults to 1.

min_height

max_height

The menu will grow no bigger than this number. Set to 0 for no limit.

max_height is a NumericProperty and defaults to 0.

border_margin

Margin between Window border and menu.

self.menu = MDDropdownMenu(
    border_margin=dp(24),
    ...,
)

border_margin is a NumericProperty and defaults to 4dp.

ver_growth

Where the menu will grow vertically to when opening. Set to None to let the widget pick for you. Available options are: ‘up’, ‘down’.

self.menu = MDDropdownMenu(
    ver_growth="up",
    ...,
)

self.menu = MDDropdownMenu(
    ver_growth="down",
    ...,
)

ver_growth is a OptionProperty and defaults to None.

hor_growth

Where the menu will grow horizontally to when opening. Set to None to let the widget pick for you. Available options are: ‘left’, ‘right’.

self.menu = MDDropdownMenu(
    hor_growth="left",
    ...,
)

self.menu = MDDropdownMenu(
    hor_growth="right",
    ...,
)

hor_growth is a OptionProperty and defaults to None.

background_color

Color in (r, g, b, a) or string format of the background of the menu.

Deprecated since version 1.2.0: Use md_bg_color instead.

background_color is a ColorProperty and defaults to None.

caller

The widget object that calls the menu window.

caller is a ObjectProperty and defaults to None.

position

Menu window position relative to parent element. Available options are: ‘auto’, ‘top’, ‘center’, ‘bottom’.

See Position for more information.

position is a OptionProperty and defaults to ‘auto’.

radius

Menu radius.

radius is a VariableListProperty and defaults to ‘[dp(7)]’.

adjust_width() → None

Adjust the width of the menu if the width of the menu goes beyond the boundaries of the parent window from starting point.

check_ver_growth() → None

Checks whether the height of the lower/upper borders of the menu exceeds the limits borders of the parent window.

check_hor_growth() → None

Checks whether the width of the left/right menu borders exceeds the boundaries of the parent window.

get_target_pos() → [float, float]

set_target_height() → None

Set the target height of the menu depending on the size of each item.

set_menu_properties(*args) → None

Sets the size and position for the menu window.

set_menu_pos(*args) → None

adjust_position() → str

Return value ‘auto’ for the menu position if the menu position is out of screen.

open() → None

Animate the opening of a menu window.

on_items(instance, value: list) → None

The method sets the class that will be used to create the menu item.

on_header_cls(instance_dropdown_menu, instance_user_menu_header) → None

Called when a value is set to the header_cls parameter.

on_touch_down(touch)

Receive a touch down event.

Parameters:

touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_move(touch)

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

dismiss(*args) → None

Closes the menu.