NavigationDrawer#

Anatomy#

Root:

    MDNavigationLayout:

        MDScreenManager:

            Screen_1:

            Screen_2:

        MDNavigationDrawer:

            # This custom rule should implement what will be appear in your
            # MDNavigationDrawer.
            ContentNavigationDrawer:

A simple example#

from kivy.lang import Builder

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

KV = '''
MDScreen:

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                MDTopAppBar:
                    title: "Navigation Drawer"
                    elevation: 4
                    pos_hint: {"top": 1}
                    md_bg_color: "#e7e4c0"
                    specific_text_color: "#4a4939"
                    left_action_items:
                        [['menu', lambda x: nav_drawer.set_state("open")]]


        MDNavigationDrawer:
            id: nav_drawer
            radius: (0, 16, 16, 0)

            ContentNavigationDrawer:
'''


class ContentNavigationDrawer(MDBoxLayout):
    pass


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.navigationdrawer import MDNavigationLayout, MDNavigationDrawer
from kivymd.uix.screen import MDScreen
from kivymd.uix.screenmanager import MDScreenManager
from kivymd.uix.toolbar import MDTopAppBar


class ContentNavigationDrawer(MDBoxLayout):
    pass


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return(
            MDScreen(
                MDNavigationLayout(
                    MDScreenManager(
                        MDScreen(
                            MDTopAppBar(
                                title="Navigation Drawer",
                                elevation=4,
                                pos_hint={"top": 1},
                                md_bg_color="#e7e4c0",
                                specific_text_color="#4a4939",
                                left_action_items=[
                                    ['menu', lambda x: self.nav_drawer_open()]
                                ],
                            )

                        )
                    ),
                    MDNavigationDrawer(
                        ContentNavigationDrawer(),
                        id="nav_drawer",
                        radius=(0, 16, 16, 0),
                    ),
                ),
            ),
        )

    def nav_drawer_open(self, *args):
        nav_drawer = self.root.children[0].ids.nav_drawer
        nav_drawer.set_state("open")


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer.gif

Note

MDNavigationDrawer is an empty MDCard panel.

Standard content for the navigation bar#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<DrawerClickableItem@MDNavigationDrawerItem>
    focus_color: "#e7e4c0"
    text_color: "#4a4939"
    icon_color: "#4a4939"
    ripple_color: "#c5bdd2"
    selected_color: "#0c6c4d"


<DrawerLabelItem@MDNavigationDrawerItem>
    text_color: "#4a4939"
    icon_color: "#4a4939"
    focus_behavior: False
    selected_color: "#4a4939"
    _no_ripple_effect: True


MDScreen:

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                MDTopAppBar:
                    title: "Navigation Drawer"
                    elevation: 4
                    pos_hint: {"top": 1}
                    md_bg_color: "#e7e4c0"
                    specific_text_color: "#4a4939"
                    left_action_items: [["menu", lambda x: nav_drawer.set_state("open")]]

        MDNavigationDrawer:
            id: nav_drawer
            radius: (0, 16, 16, 0)

            MDNavigationDrawerMenu:

                MDNavigationDrawerHeader:
                    title: "Header title"
                    title_color: "#4a4939"
                    text: "Header text"
                    spacing: "4dp"
                    padding: "12dp", 0, 0, "56dp"

                MDNavigationDrawerLabel:
                    text: "Mail"

                DrawerClickableItem:
                    icon: "gmail"
                    right_text: "+99"
                    text_right_color: "#4a4939"
                    text: "Inbox"

                DrawerClickableItem:
                    icon: "send"
                    text: "Outbox"

                MDNavigationDrawerDivider:

                MDNavigationDrawerLabel:
                    text: "Labels"

                DrawerLabelItem:
                    icon: "information-outline"
                    text: "Label"

                DrawerLabelItem:
                    icon: "information-outline"
                    text: "Label"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()

from kivymd.app import MDApp
from kivymd.uix.navigationdrawer import (
    MDNavigationLayout,
    MDNavigationDrawer,
    MDNavigationDrawerMenu,
    MDNavigationDrawerHeader,
    MDNavigationDrawerLabel,
    MDNavigationDrawerDivider,
    MDNavigationDrawerItem,
)
from kivymd.uix.screen import MDScreen
from kivymd.uix.screenmanager import MDScreenManager
from kivymd.uix.toolbar import MDTopAppBar


class BaseNavigationDrawerItem(MDNavigationDrawerItem):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.radius = 24
        self.text_color = "#4a4939"
        self.icon_color = "#4a4939"
        self.focus_color = "#e7e4c0"


class DrawerLabelItem(BaseNavigationDrawerItem):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.focus_behavior = False
        self._no_ripple_effect = True
        self.selected_color = "#4a4939"


class DrawerClickableItem(BaseNavigationDrawerItem):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.ripple_color = "#c5bdd2"
        self.selected_color = "#0c6c4d"


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return(
            MDScreen(
                MDNavigationLayout(
                    MDScreenManager(
                        MDScreen(
                            MDTopAppBar(
                                title="Navigation Drawer",
                                elevation=4,
                                pos_hint={"top": 1},
                                md_bg_color="#e7e4c0",
                                specific_text_color="#4a4939",
                                left_action_items=[
                                    ['menu', lambda x: self.nav_drawer_open()]
                                ],
                            )

                        )
                    ),
                    MDNavigationDrawer(
                        MDNavigationDrawerMenu(
                            MDNavigationDrawerHeader(
                                title="Header title",
                                title_color="#4a4939",
                                text="Header text",
                                spacing="4dp",
                                padding=("12dp", 0, 0, "56dp"),
                            ),
                            MDNavigationDrawerLabel(
                                text="Mail",
                            ),
                            DrawerClickableItem(
                                icon="gmail",
                                right_text="+99",
                                text_right_color="#4a4939",
                                text="Inbox",
                            ),
                            DrawerClickableItem(
                                icon="send",
                                text="Outbox",
                            ),
                            MDNavigationDrawerDivider(),
                            MDNavigationDrawerLabel(
                                text="Labels",
                            ),
                            DrawerLabelItem(
                                icon="information-outline",
                                text="Label",
                            ),
                            DrawerLabelItem(
                                icon="information-outline",
                                text="Label",
                            ),
                        ),
                        id="nav_drawer",
                        radius=(0, 16, 16, 0),
                    )
                )
            )
        )

    def nav_drawer_open(self, *args):
        nav_drawer = self.root.children[0].ids.nav_drawer
        nav_drawer.set_state("open")


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-standatd-content.gif

Switching screens in the `ScreenManager` and using the common `MDTopAppBar`#

from kivy.lang import Builder
from kivy.properties import ObjectProperty

from kivymd.app import MDApp
from kivymd.uix.scrollview import MDScrollView

KV = '''
<ContentNavigationDrawer>

    MDList:

        OneLineListItem:
            text: "Screen 1"
            on_press:
                root.nav_drawer.set_state("close")
                root.screen_manager.current = "scr 1"

        OneLineListItem:
            text: "Screen 2"
            on_press:
                root.nav_drawer.set_state("close")
                root.screen_manager.current = "scr 2"


MDScreen:

    MDTopAppBar:
        pos_hint: {"top": 1}
        elevation: 4
        title: "MDNavigationDrawer"
        left_action_items: [["menu", lambda x: nav_drawer.set_state("open")]]

    MDNavigationLayout:

        MDScreenManager:
            id: screen_manager

            MDScreen:
                name: "scr 1"

                MDLabel:
                    text: "Screen 1"
                    halign: "center"

            MDScreen:
                name: "scr 2"

                MDLabel:
                    text: "Screen 2"
                    halign: "center"

        MDNavigationDrawer:
            id: nav_drawer
            radius: (0, 16, 16, 0)

            ContentNavigationDrawer:
                screen_manager: screen_manager
                nav_drawer: nav_drawer
'''


class ContentNavigationDrawer(MDScrollView):
    screen_manager = ObjectProperty()
    nav_drawer = ObjectProperty()


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


Example().run()

from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.uix.list import MDList, OneLineListItem
from kivymd.uix.navigationdrawer import MDNavigationLayout, MDNavigationDrawer
from kivymd.uix.screen import MDScreen
from kivymd.uix.screenmanager import MDScreenManager
from kivymd.uix.scrollview import MDScrollView
from kivymd.uix.toolbar import MDTopAppBar


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Dark"
        return (
            MDScreen(
                MDTopAppBar(
                    pos_hint={"top": 1},
                    elevation=4,
                    title="MDNavigationDrawer",
                    left_action_items=[["menu", lambda x: self.nav_drawer_open()]],
                ),
                MDNavigationLayout(
                    MDScreenManager(
                        MDScreen(
                            MDLabel(
                                text="Screen 1",
                                halign="center",
                            ),
                            name="scr 1",
                        ),
                        MDScreen(
                            MDLabel(
                                text="Screen 2",
                                halign="center",
                            ),
                            name="scr 2",
                        ),
                        id="screen_manager",
                    ),
                    MDNavigationDrawer(
                        MDScrollView(
                            MDList(
                                OneLineListItem(
                                    text="Screen 1",
                                    on_press=self.switch_screen,
                                ),
                                OneLineListItem(
                                    text="Screen 2",
                                    on_press=self.switch_screen,
                                ),
                            ),
                        ),
                        id="nav_drawer",
                        radius=(0, 16, 16, 0),
                    ),
                    id="navigation_layout",
                )
            )
        )

    def switch_screen(self, instance_list_item: OneLineListItem):
        self.root.ids.navigation_layout.ids.screen_manager.current = {
            "Screen 1": "scr 1", "Screen 2": "scr 2"
        }[instance_list_item.text]
        self.root.children[0].ids.nav_drawer.set_state("close")

    def nav_drawer_open(self):
        nav_drawer = self.root.children[0].ids.nav_drawer
        nav_drawer.set_state("open")


Example().run()

API - `kivymd.uix.navigationdrawer.navigationdrawer`#

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationLayout(*args, **kwargs)#

For more information, see in the MDFloatLayout class documentation.

update_pos(self, instance_navigation_drawer, pos_x: float)#

add_scrim(self, instance_manager: ScreenManager)#

update_scrim_rectangle(self, instance_manager: ScreenManager, size: list)#

add_widget(self, widget, index=0, canvas=None)#: Only two layouts are allowed: ScreenManager and MDNavigationDrawer.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerLabel(*args, **kwargs)#

Implements a label for a menu for MDNavigationDrawer class.

For more information, see in the MDBoxLayout class documentation.

New in version 1.0.0.

MDNavigationDrawer:

    MDNavigationDrawerMenu:

        MDNavigationDrawerLabel:
            text: "Mail"

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-label.png

text#

Text label.

text is a StringProperty and defaults to ‘’.

padding#

Padding between layout box and children: [padding_left, padding_top, padding_right, padding_bottom].

Padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].

padding is a VariableListProperty and defaults to [‘20dp’, 0, 0, ‘8dp’].

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerDivider(*args, **kwargs)#

Implements a divider for a menu for MDNavigationDrawer class.

For more information, see in the MDBoxLayout class documentation.

New in version 1.0.0.

MDNavigationDrawer:

    MDNavigationDrawerMenu:

        MDNavigationDrawerLabel:
            text: "Mail"

        MDNavigationDrawerDivider:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-divider.png

padding#

Padding between layout box and children: [padding_left, padding_top, padding_right, padding_bottom].

Padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].

padding is a VariableListProperty and defaults to [‘20dp’, ‘12dp’, 0, ‘12dp’].

color#

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

color is a ColorProperty and defaults to None.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerHeader(**kwargs)#

Implements a header for a menu for MDNavigationDrawer class.

For more information, see in the MDBoxLayout class documentation.

New in version 1.0.0.

MDNavigationDrawer:

    MDNavigationDrawerMenu:

        MDNavigationDrawerHeader:
            title: "Header title"
            text: "Header text"
            spacing: "4dp"
            padding: "12dp", 0, 0, "56dp"

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-header.png

source#

Image logo path.

MDNavigationDrawer:

    MDNavigationDrawerMenu:

        MDNavigationDrawerHeader:
            title: "Header title"
            text: "Header text"
            source: "logo.png"
            spacing: "4dp"
            padding: "12dp", 0, 0, "56dp"

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-header-source.png

source is a StringProperty and defaults to ‘’.

title#

Title shown in the first line.

title is a StringProperty and defaults to ‘’.

title_halign#

Title halign first line.

title_halign is a StringProperty and defaults to ‘left’.

title_color#

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

title_color is a ColorProperty and defaults to None.

title_font_style#

Title shown in the first line.

title_font_style is a StringProperty and defaults to ‘H4’.

title_font_size#

Title shown in the first line.

title_font_size is a StringProperty and defaults to ’34sp’.

text#

Text shown in the second line.

text is a StringProperty and defaults to ‘’.

text_halign#

Text halign first line.

text_halign is a StringProperty and defaults to ‘left’.

text_color#

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

text_color is a ColorProperty and defaults to None.

text_font_style#

Title shown in the first line.

text_font_style is a StringProperty and defaults to ‘H6’.

text_font_size#

Title shown in the first line.

text_font_size is a StringProperty and defaults to ’20sp’.

check_content(self, interval: int | float)#: Removes widgets that the user has not added to the container.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItem(*args, **kwargs)#

Implements an item for the MDNavigationDrawer menu list.

For more information, see in the OneLineAvatarIconListItem and FocusBehavior class documentation.

New in version 1.0.0.

MDNavigationDrawer:

    MDNavigationDrawerMenu:

        MDNavigationDrawerHeader:
            title: "Header title"
            text: "Header text"
            spacing: "4dp"
            padding: "12dp", 0, 0, "56dp"

        MDNavigationDrawerItem
            icon: "gmail"
            right_text: "+99"
            text: "Inbox"

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-item.png

selected#

Is the item selected.

selected is a BooleanProperty and defaults to False.

icon#

Icon item.

icon is a StringProperty and defaults to ‘’.

icon_color#

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

icon_color is a ColorProperty and defaults to None.

selected_color#

The color in (r, g, b, a) or string format of the icon and text of the selected item.

selected_color is a ColorProperty and defaults to [0, 0, 0, 1].

right_text#

Right text item.

right_text is a StringProperty and defaults to ‘’.

text_right_color#

Right text color item in (r, g, b, a) or string format.

text_right_color is a ColorProperty and defaults to None.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerMenu(*args, **kwargs)#

Implements a scrollable list for menu items of the MDNavigationDrawer class.

For more information, see in the MDScrollView class documentation.

New in version 1.0.0.

MDNavigationDrawer:

    MDNavigationDrawerMenu:

        # Your menu items.
        ...

spacing#

Spacing between children, in pixels.

spacing is a NumericProperty and defaults to 0.

add_widget(self, widget, *args, **kwargs)#

Add a new widget as a child of this widget.

Parameters:

widget: Widget
Widget to add to our list of children.

index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

reset_active_color(self, item: MDNavigationDrawerItem)#

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawer(*args, **kwargs)#

Card class.

For more information, see in the DeclarativeBehavior and MDAdaptiveWidget and ThemableBehavior and BackgroundColorBehavior and RectangularRippleBehavior and CommonElevationBehavior and FocusBehavior and BoxLayout and classes documentation.

type#

Type of drawer. Modal type will be on top of screen. Standard type will be at left or right of screen. Also it automatically disables close_on_click and enable_swiping to prevent closing drawer for standard type.

For more information, see in the MDCard class documentation.

Standard#

MDNavigationDrawer:
    type: "standard"

anchor#

Anchoring screen edge for drawer. Set it to ‘right’ for right-to-left languages. Available options are: ‘left’, ‘right’.

Left#

MDNavigationDrawer:
    anchor: "left"

Right#

MDNavigationDrawer:
    anchor: "right"

anchor is a OptionProperty and defaults to ‘left’.

scrim_color#

Color for scrim in (r, g, b, a) or string format. Alpha channel will be multiplied with _scrim_alpha. Set fourth channel to 0 if you want to disable scrim.

MDNavigationDrawer:
    scrim_color: 0, 0, 0, .8
    # scrim_color: 0, 0, 0, .2

scrim_color is a ColorProperty and defaults to [0, 0, 0, 0.5].

padding#

Padding between layout box and children: [padding_left, padding_top, padding_right, padding_bottom].

Padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].

Changed in version 1.0.0.

MDNavigationDrawer:
    padding: 56, 56, 12, 16

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-padding.png

padding is a VariableListProperty and defaults to ‘[16, 16, 12, 16]’.

close_on_click#

Close when click on scrim or keyboard escape. It automatically sets to False for “standard” type.

close_on_click is a BooleanProperty and defaults to True.

state#

Indicates if panel closed or opened. Sets after status change. Available options are: ‘close’, ‘open’.

state is a OptionProperty and defaults to ‘close’.

status#

Detailed state. Sets before state. Bind to state instead of status. Available options are: ‘closed’, ‘opening_with_swipe’, ‘opening_with_animation’, ‘opened’, ‘closing_with_swipe’, ‘closing_with_animation’.

status is a OptionProperty and defaults to ‘closed’.

open_progress#

Percent of visible part of side panel. The percent is specified as a floating point number in the range 0-1. 0.0 if panel is closed and 1.0 if panel is opened.

open_progress is a NumericProperty and defaults to 0.0.

enable_swiping#

Allow to open or close navigation drawer with swipe. It automatically sets to False for “standard” type.

enable_swiping is a BooleanProperty and defaults to True.

swipe_distance#

The distance of the swipe with which the movement of navigation drawer begins.

swipe_distance is a NumericProperty and defaults to 10.

swipe_edge_width#

The size of the area in px inside which should start swipe to drag navigation drawer.

swipe_edge_width is a NumericProperty and defaults to 20.

scrim_alpha_transition#

The name of the animation transition type to use for changing scrim_alpha.

scrim_alpha_transition is a StringProperty and defaults to ‘linear’.

opening_transition#

The name of the animation transition type to use when animating to the state ‘open’.

opening_transition is a StringProperty and defaults to ‘out_cubic’.

opening_time#

The time taken for the panel to slide to the state ‘open’.

opening_time is a NumericProperty and defaults to 0.2.

closing_transition#

The name of the animation transition type to use when animating to the state ‘close’.

closing_transition is a StringProperty and defaults to ‘out_sine’.

closing_time#

The time taken for the panel to slide to the state ‘close’.

closing_time is a NumericProperty and defaults to 0.2.

set_state(self, new_state='toggle', animation=True)#: Change state of the side panel. New_state can be one of “toggle”, “open” or “close”.

update_status(self, *_)#

get_dist_from_side(self, x: float)#

on_touch_down(self, 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(self, touch)#

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

See on_touch_down() for more information.

on_touch_up(self, touch)#

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

See on_touch_down() for more information.

on_radius(self, instance_navigation_drawer, radius_value: list)#

on_type(self, instance_navigation_drawer, drawer_type: str)#

NavigationDrawer#

Anatomy#

A simple example#

Standard content for the navigation bar#

Switching screens in the ScreenManager and using the common MDTopAppBar#

API - kivymd.uix.navigationdrawer.navigationdrawer#

Standard#

Modal#

Left#

Right#

Switching screens in the `ScreenManager` and using the common `MDTopAppBar`#

API - `kivymd.uix.navigationdrawer.navigationdrawer`#