NavigationDrawer

Navigation drawers provide access to destinations in your app.

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

When using the class MDNavigationDrawer skeleton of your KV markup should look like this:

Anatomy

Root:

    MDNavigationLayout:

        ScreenManager:

            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 = '''
#:import get_color_from_hex kivy.utils.get_color_from_hex


MDScreen:

    MDNavigationLayout:

        ScreenManager:

            MDScreen:

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


        MDNavigationDrawer:
            id: nav_drawer
            md_bg_color: get_color_from_hex("#f7f4e7")

            ContentNavigationDrawer:
'''


class ContentNavigationDrawer(MDBoxLayout):
    pass


class TestNavigationDrawer(MDApp):
    def build(self):
        return Builder.load_string(KV)


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

Note

MDNavigationDrawer is an empty MDCard panel.

Custom content for navigation drawer

Let’s extend the ContentNavigationDrawer class from the above example and create content for our MDNavigationDrawer panel:

# Menu item in the DrawerList list.
<ItemDrawer>
    theme_text_color: "Custom"
    on_release: self.parent.set_color_item(self)

    IconLeftWidget:
        id: icon
        icon: root.icon
        theme_text_color: "Custom"
        text_color: root.text_color
class ItemDrawer(OneLineIconListItem):
    icon = StringProperty()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/drawer-item.png

Top of ContentNavigationDrawer and DrawerList for menu items:

<ContentNavigationDrawer>
    orientation: "vertical"
    padding: "8dp"
    spacing: "8dp"

    AnchorLayout:
        anchor_x: "left"
        size_hint_y: None
        height: avatar.height

        Image:
            id: avatar
            size_hint: None, None
            size: "56dp", "56dp"
            source: "kivymd.png"

    MDLabel:
        text: "KivyMD library"
        font_style: "Button"
        size_hint_y: None
        height: self.texture_size[1]

    MDLabel:
        text: "kivydevelopment@gmail.com"
        font_style: "Caption"
        size_hint_y: None
        height: self.texture_size[1]

    ScrollView:

        DrawerList:
            id: md_list
class ContentNavigationDrawer(BoxLayout):
    pass


class DrawerList(ThemableBehavior, MDList):
    def set_color_item(self, instance_item):
        '''Called when tap on a menu item.'''

        # Set the color of the icon and text for the menu item.
        for item in self.children:
            if item.text_color == self.theme_cls.primary_color:
                item.text_color = self.theme_cls.text_color
                break
        instance_item.text_color = self.theme_cls.primary_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/drawer-top.png

Create a menu list for ContentNavigationDrawer:

def on_start(self):
    icons_item = {
        "folder": "My files",
        "account-multiple": "Shared with me",
        "star": "Starred",
        "history": "Recent",
        "checkbox-marked": "Shared with me",
        "upload": "Upload",
    }
    for icon_name in icons_item.keys():
        self.root.ids.content_drawer.ids.md_list.add_widget(
            ItemDrawer(icon=icon_name, text=icons_item[icon_name])
        )
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/drawer-work.gif

Standard content for the navigation bar

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
#:import get_color_from_hex kivy.utils.get_color_from_hex

#:set text_color get_color_from_hex("#4a4939")
#:set focus_color get_color_from_hex("#e7e4c0")
#:set ripple_color get_color_from_hex("#c5bdd2")
#:set bg_color get_color_from_hex("#f7f4e7")
#:set selected_color get_color_from_hex("#0c6c4d")


<DrawerClickableItem@MDNavigationDrawerItem>
    focus_color: focus_color
    unfocus_color: bg_color
    text_color: text_color
    icon_color: text_color
    ripple_color: ripple_color
    selected_color: selected_color


<DrawerLabelItem@MDNavigationDrawerItem>
    bg_color: bg_color
    text_color: text_color
    icon_color: text_color
    _no_ripple_effect: True


MDScreen:

    MDNavigationLayout:

        ScreenManager:

            MDScreen:

                MDToolbar:
                    title: "Navigation Drawer"
                    elevation: 10
                    pos_hint: {"top": 1}
                    md_bg_color: focus_color
                    specific_text_color: text_color
                    left_action_items:
                        [                             [                             'menu', lambda x:                             nav_drawer.set_state("open")                             if nav_drawer.state == "close" else                             nav_drawer.set_state("close")                             ]                             ]

        MDNavigationDrawer:
            id: nav_drawer
            radius: (0, 16, 16, 0) if self.anchor == "left" else (16, 0, 0, 16)
            md_bg_color: bg_color

            MDNavigationDrawerMenu:

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

                MDNavigationDrawerLabel:
                    text: "Mail"

                DrawerClickableItem:
                    icon: "gmail"
                    right_text: "+99"
                    text_right_color: text_color
                    text: "Inbox"

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

                MDNavigationDrawerDivider:

                MDNavigationDrawerLabel:
                    text: "Labels"

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

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


class TestNavigationDrawer(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Indigo"
        return Builder.load_string(KV)


TestNavigationDrawer().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 MDToolbar

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

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

KV = '''
<ContentNavigationDrawer>

    ScrollView:

        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:

    MDToolbar:
        id: toolbar
        pos_hint: {"top": 1}
        elevation: 10
        title: "MDNavigationDrawer"
        left_action_items: [["menu", lambda x: nav_drawer.set_state("open")]]

    MDNavigationLayout:
        x: toolbar.height

        ScreenManager:
            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

            ContentNavigationDrawer:
                screen_manager: screen_manager
                nav_drawer: nav_drawer
'''


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


class TestNavigationDrawer(MDApp):
    def build(self):
        return Builder.load_string(KV)


TestNavigationDrawer().run()

API - kivymd.uix.navigationdrawer.navigationdrawer

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationLayout(**kwargs)

Float layout class. See module documentation for more information.

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(**kwargs)

Implements a label for a menu for MDNavigationDrawer class.

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(**kwargs)

Implements a divider for a menu for MDNavigationDrawer class.

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 rgba 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.

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.

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.

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: Union[int, float])

Removes widgets that the user has not added to the container.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItem(**kwargs)

Implements an item for the MDNavigationDrawer menu list.

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 item.

icon_color is a ColorProperty and defaults to None.

selected_color

The color 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.

text_right_color is a ColorProperty and defaults to None.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerMenu(**kwargs)

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

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(**kwargs)

Common base class for rectangular and circular elevation behavior.

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.

MDNavigationDrawer:
    type: "standard"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-standard.gif
MDNavigationDrawer:
    type: "modal"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-modal.gif

type is a OptionProperty and defaults to ‘modal’.

anchor

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

MDNavigationDrawer:
    anchor: "left"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-type-left.png
MDNavigationDrawer:
    anchor: "right"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-type-right.png

anchor is a OptionProperty and defaults to ‘left’.

scrim_color

Color for scrim. Alpha channel will be multiplied with _scrim_alpha. Set fourth channel to 0 if you want to disable scrim.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-scrim-color.png
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)