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:

        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: 10
                    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
            md_bg_color: "#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 = '''
<DrawerClickableItem@MDNavigationDrawerItem>
    focus_color: "#e7e4c0"
    unfocus_color: "#f7f4e7"
    text_color: "#4a4939"
    icon_color: "#4a4939"
    ripple_color: "#c5bdd2"
    selected_color: "#0c6c4d"


<DrawerLabelItem@MDNavigationDrawerItem>
    bg_color: "#f7f4e7"
    text_color: "#4a4939"
    icon_color: "#4a4939"
    _no_ripple_effect: True


MDScreen:

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                MDTopAppBar:
                    title: "Navigation Drawer"
                    elevation: 10
                    pos_hint: {"top": 1}
                    md_bg_color: "#e7e4c0"
                    specific_text_color: "#4a4939"
                    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: "#f7f4e7"

            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 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 MDTopAppBar#

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:

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

        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

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

Implements the creation and addition of child widgets as declarative programming style.

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.

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.

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

Implements the creation and addition of child widgets as declarative programming style.

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)#