NavigationDrawer

See also

Material Design, Navigation drawer

Navigation drawers provide access to destinations in your app.

• Use navigation drawers in expanded layouts and modal navigation drawers in compact and medium layouts

• Can be open or closed by default

• Two types: standard and modal

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

Usage

Root:

    MDNavigationLayout:

        MDScreenManager:

            Screen_1:

            Screen_2:

        MDNavigationDrawer:

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

A simple example

Declarative KV stylesDeclarative python styles

from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                MDButton:
                    pos_hint: {"center_x": .5, "center_y": .5}
                    on_release: nav_drawer.set_state("toggle")

                    MDButtonText:
                        text: "Open Drawer"

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

            MDNavigationDrawerMenu:

                MDNavigationDrawerLabel:
                    text: "Mail"

                MDNavigationDrawerItem:

                    MDNavigationDrawerItemLeadingIcon:
                        icon: "account"

                    MDNavigationDrawerItemText:
                        text: "Inbox"

                    MDNavigationDrawerItemTrailingText:
                        text: "24"

                MDNavigationDrawerDivider:
'''


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


Example().run()

Anatomy

Note

MDNavigationDrawer is an empty MDCard panel.

Item anatomy

MDNavigationDrawerItem:

    MDNavigationDrawerItemLeadingIcon:
        icon: "account"

    MDNavigationDrawerItemText:
        text: "Inbox"

    MDNavigationDrawerItemTrailingText:
        text: "24"

Type drawer

Standard

MDNavigationDrawer:
    drawer_type: "standard"

Modal

MDNavigationDrawer:
    drawer_type: "modal"

Anchoring screen edge for drawer

MDNavigationDrawer:
    anchor: "left"

MDNavigationDrawer:
    anchor: "right"

API break

1.2.0 version

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:

                MDRaisedButton:
                    text: "Open Drawer"
                    pos_hint: {"center_x": .5, "center_y": .5}
                    on_release: nav_drawer.set_state("toggle")

        MDNavigationDrawer:
            id: nav_drawer
            radius: (0, dp(16), dp(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):
        return Builder.load_string(KV)


Example().run()

2.2.0 version

from kivy.lang import Builder
from kivy.properties import StringProperty, ColorProperty

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.navigationdrawer import (
    MDNavigationDrawerItem, MDNavigationDrawerItemTrailingText
)

KV = '''
<DrawerItem>
    active_indicator_color: "#e7e4c0"

    MDNavigationDrawerItemLeadingIcon:
        icon: root.icon
        theme_icon_color: "Custom"
        icon_color: "#4a4939"

    MDNavigationDrawerItemText:
        text: root.text
        theme_text_color: "Custom"
        text_color: "#4a4939"


<DrawerLabel>
    adaptive_height: True
    padding: "18dp", 0, 0, "12dp"

    MDNavigationDrawerItemLeadingIcon:
        icon: root.icon
        theme_icon_color: "Custom"
        icon_color: "#4a4939"
        pos_hint: {"center_y": .5}

    MDNavigationDrawerLabel:
        text: root.text
        theme_text_color: "Custom"
        text_color: "#4a4939"
        pos_hint: {"center_y": .5}
        padding: "6dp", 0, "16dp", 0
        theme_line_height: "Custom"
        line_height: 0


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                MDButton:
                    pos_hint: {"center_x": .5, "center_y": .5}
                    on_release: nav_drawer.set_state("toggle")

                    MDButtonText:
                        text: "Open Drawer"

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

            MDNavigationDrawerMenu:

                MDNavigationDrawerHeader:
                    orientation: "vertical"
                    padding: 0, 0, 0, "12dp"
                    adaptive_height: True

                    MDLabel:
                        text: "Header title"
                        theme_text_color: "Custom"
                        theme_line_height: "Custom"
                        line_height: 0
                        text_color: "#4a4939"
                        adaptive_height: True
                        padding_x: "16dp"
                        font_style: "Display"
                        role: "small"

                    MDLabel:
                        text: "Header text"
                        padding_x: "18dp"
                        adaptive_height: True
                        font_style: "Title"
                        role: "large"

                MDNavigationDrawerDivider:

                DrawerItem:
                    icon: "gmail"
                    text: "Inbox"
                    trailing_text: "+99"
                    trailing_text_color: "#4a4939"

                DrawerItem:
                    icon: "send"
                    text: "Outbox"

                MDNavigationDrawerDivider:

                MDNavigationDrawerLabel:
                    text: "Labels"
                    padding_y: "12dp"

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

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


class DrawerLabel(MDBoxLayout):
    icon = StringProperty()
    text = StringProperty()


class DrawerItem(MDNavigationDrawerItem):
    icon = StringProperty()
    text = StringProperty()
    trailing_text = StringProperty()
    trailing_text_color = ColorProperty()

    _trailing_text_obj = None

    def on_trailing_text(self, instance, value):
        self._trailing_text_obj = MDNavigationDrawerItemTrailingText(
            text=value,
            theme_text_color="Custom",
            text_color=self.trailing_text_color,
        )
        self.add_widget(self._trailing_text_obj)

    def on_trailing_text_color(self, instance, value):
        self._trailing_text_obj.text_color = value


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


Example().run()

API - kivymd.uix.navigationdrawer.navigationdrawer

class kivymd.uix.navigationdrawer.navigationdrawer.BaseNavigationDrawerItem

Implement the base class for the menu list item.

New in version 2.0.0.

selected

Is the item selected.

selected is a BooleanProperty and defaults to False.

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

For more information, see in the DeclarativeBehavior and FloatLayout classes documentation.

update_pos(instance_navigation_drawer, pos_x: float) → None

add_scrim(instance_manager: kivy.uix.screenmanager.ScreenManager) → None

update_scrim_rectangle(instance_manager: kivy.uix.screenmanager.ScreenManager, size: list) → None

add_widget(widget, index=0, canvas=None)

Only two layouts are allowed: ScreenManager and MDNavigationDrawer.

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

Implements a label class.

For more information, see in the MDLabel class documentation.

New in version 1.0.0.

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

Implements a divider class.

For more information, see in the BoxLayout class documentation.

New in version 1.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerHeader(*args, **kwargs)

Implements a header class.

For more information, see in the DeclarativeBehavior and BoxLayout classes documentation.

New in version 1.0.0.

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

Implements an item for the MDNavigationDrawer menu list.

For more information, see in the MDListItem and FocusBehavior and BaseNavigationDrawerItem classes documentation.

New in version 1.0.0.

active_indicator_color

The active indicator color in (r, g, b, a) or string format.

New in version 2.0.0.

active_indicator_color is a ColorProperty and defaults to None.

inactive_indicator_color

The inactive indicator color in (r, g, b, a) or string format.

New in version 2.0.0.

inactive_indicator_color is a ColorProperty and defaults to None.

add_widget(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)

on_release(*args) → None

Fired when the item is released (i.e. the touch/click that pressed the item goes away).

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemLeadingIcon(*args, **kwargs)

Implements the leading icon for the menu list item.

For more information, see in the MDListItemLeadingIcon and BaseNavigationDrawerItem classes documentation.

New in version 2.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemText(*args, **kwargs)

Implements the text for the menu list item.

For more information, see in the MDListItemSupportingText and BaseNavigationDrawerItem classes documentation.

New in version 2.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemTrailingText(*args, **kwargs)

Implements the supporting text for the menu list item.

For more information, see in the MDListItemTrailingSupportingText and BaseNavigationDrawerItem classes documentation.

New in version 2.0.0.

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

update_items_color(item: MDNavigationDrawerItem) → None

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

Navigation drawer class.

For more information, see in the MDCard class documentation.

Events:

New in version 2.0.0.

on_open:

Fired when the navigation drawer is opened.

on_close:

Fired when the navigation drawer is closed.

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

Changed in version 2.0.0: Rename from type to drawer_type.

drawer_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’.

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.

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: "56dp"

padding is a VariableListProperty and defaults to ‘[dp(16), dp(16), dp(12), dp(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.

background_color

The drawer background color in (r, g, b, a) or string format.

New in version 2.0.0.

background_color is a ColorProperty and defaults to None.

theme_elevation_level = 'Custom'

Drawer elevation level scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_elevation_level is an OptionProperty and defaults to ‘Custom’.

elevation_level = 1

Drawer elevation level (values from 0 to 5)

New in version 2.2.0.

elevation_level is an BoundedNumericProperty and defaults to 2.

set_properties_widget() → None

Fired on_release/on_press/on_enter/on_leave events.

set_state(new_state='toggle', animation=True) → None

Change state of the side panel. New_state can be one of “toggle”, “open” or “close”.

update_status(*args) → None

get_dist_from_side(x: float) → float

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.

on_radius(instance_navigation_drawer, radius_value: list) → None

Fired when the radius value changes.

on_drawer_type(instance_navigation_drawer, drawer_type: str) → None

Fired when the drawer_type value changes.

on_open(*args) → None

Fired when the navigation drawer is opened.

on_close(*args) → None

Fired when the navigation drawer is closed.