NavigationDrawer#
#
See also
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:
Root(
MDNavigationLayout(
MDScreenManager(
Screen_1(
...
),
Screen_2(
...
),
),
MDNavigationDrawer(
# This custom rule should implement what will be displayed in
# your MDNavigationDrawer.
ContentNavigationDrawer(
...
)
)
)
)
A simple example#
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()
from kivy.metrics import dp
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.screenmanager import MDScreenManager
from kivymd.uix.navigationdrawer import (
MDNavigationLayout,
MDNavigationDrawer,
MDNavigationDrawerMenu,
MDNavigationDrawerLabel,
MDNavigationDrawerItem,
MDNavigationDrawerItemLeadingIcon,
MDNavigationDrawerItemText,
MDNavigationDrawerItemTrailingText,
MDNavigationDrawerDivider,
)
from kivymd.uix.screen import MDScreen
from kivymd.app import MDApp
class Example(MDApp):
def build(self):
return MDScreen(
MDNavigationLayout(
MDScreenManager(
MDScreen(
MDButton(
MDButtonText(
text="Open Drawer",
),
on_release=lambda x: self.root.get_ids().nav_drawer.set_state(
"toggle"
),
pos_hint={"center_x": 0.5, "center_y": 0.5},
),
),
),
MDNavigationDrawer(
MDNavigationDrawerMenu(
MDNavigationDrawerLabel(
text="Mail",
),
MDNavigationDrawerItem(
MDNavigationDrawerItemLeadingIcon(
icon="account",
),
MDNavigationDrawerItemText(
text="Inbox",
),
MDNavigationDrawerItemTrailingText(
text="24",
),
),
MDNavigationDrawerDivider(
),
),
id="nav_drawer",
radius=(0, dp(16), dp(16), 0),
),
),
md_bg_color=self.theme_cls.backgroundColor,
)
Example().run()
Anatomy#
Note
MDNavigationDrawer is an empty
MDCard panel.
Item anatomy#
MDNavigationDrawerItem:
MDNavigationDrawerItemLeadingIcon:
icon: "account"
MDNavigationDrawerItemText:
text: "Inbox"
MDNavigationDrawerItemTrailingText:
text: "24"
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#
Left#
MDNavigationDrawer: anchor: "left"
Right#
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()
from kivy.metrics import dp
from kivy.properties import StringProperty, ColorProperty
from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.label import MDLabel
from kivymd.uix.navigationdrawer import (
MDNavigationDrawerItem,
MDNavigationDrawerItemTrailingText,
MDNavigationLayout,
MDNavigationDrawer,
MDNavigationDrawerMenu,
MDNavigationDrawerHeader,
MDNavigationDrawerDivider,
MDNavigationDrawerLabel,
MDNavigationDrawerItemLeadingIcon,
MDNavigationDrawerItemText,
)
from kivymd.uix.screen import MDScreen
from kivymd.uix.screenmanager import MDScreenManager
class DrawerLabel(MDBoxLayout):
icon = StringProperty()
text = StringProperty()
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.widgets = [
MDNavigationDrawerItemLeadingIcon(
icon=self.icon,
theme_icon_color="Custom",
icon_color="#4a4939",
pos_hint={"center_y": .5},
),
MDNavigationDrawerLabel(
text=self.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,
)
]
class DrawerItem(MDNavigationDrawerItem):
icon = StringProperty()
text = StringProperty()
trailing_text = StringProperty()
trailing_text_color = ColorProperty()
_trailing_text_obj = None
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.widgets = [
MDNavigationDrawerItemLeadingIcon(
icon=self.icon,
theme_icon_color="Custom",
icon_color="#4a4939",
),
MDNavigationDrawerItemText(
text=self.text,
theme_text_color="Custom",
text_color="#4a4939",
id="DDD"
)
]
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 open_drawer(self, *args):
self.root.get_ids().nav_drawer.set_state("toggle")
def build(self):
return (
MDScreen(
MDNavigationLayout(
MDScreenManager(
MDScreen(
MDButton(
MDButtonText(
text="Open Drawer"
),
pos_hint={"center_x": .5, "center_y": .5},
on_release=self.open_drawer,
)
)
),
MDNavigationDrawer(
MDNavigationDrawerMenu(
MDNavigationDrawerHeader(
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",
),
orientation="vertical",
padding=(0, 0, 0, "12dp"),
adaptive_height=True,
),
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",
),
),
id="nav_drawer",
radius=(0, dp(16), dp(16), 0),
)
),
md_bg_color=self.theme_cls.backgroundColor
)
)
Example().run()
API - kivymd.uix.navigationdrawer.navigationdrawer#
- class kivymd.uix.navigationdrawer.navigationdrawer.BaseNavigationDrawerItem#
Implement the base class for the menu list item.
Added in version 2.0.0.
- selected#
Is the item selected.
selectedis aBooleanPropertyand defaults to False.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationLayout(*args, **kwargs)#
For more information, see in the
DeclarativeBehaviorandFloatLayoutclasses documentation.- 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:
ScreenManagerandMDNavigationDrawer.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerLabel(*args, **kwargs)#
Implements a label class.
For more information, see in the
MDLabelclass documentation.Added in version 1.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerDivider(**kwargs)#
Implements a divider class.
For more information, see in the
BoxLayoutclass documentation.Added in version 1.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerHeader(*args, **kwargs)#
Implements a header class.
For more information, see in the
DeclarativeBehaviorandBoxLayoutclasses documentation.Added in version 1.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItem(*args, **kwargs)#
Implements an item for the
MDNavigationDrawermenu list.For more information, see in the
MDListItemandStateFocusBehaviorandBaseNavigationDrawerItemclasses documentation.Added in version 1.0.0.
- active_indicator_color#
The active indicator color in (r, g, b, a) or string format.
Added in version 2.0.0.
active_indicator_coloris aColorPropertyand defaults to None.
- inactive_indicator_color#
The inactive indicator color in (r, g, b, a) or string format.
Added in version 2.0.0.
inactive_indicator_coloris aColorPropertyand 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.
Added 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.
Added in version 1.9.0.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemLeadingIcon(*args, **kwargs)#
Implements the leading icon for the menu list item.
For more information, see in the
MDListItemLeadingIconandBaseNavigationDrawerItemclasses documentation.Added 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
MDListItemSupportingTextandBaseNavigationDrawerItemclasses documentation.Added 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
MDListItemTrailingSupportingTextandBaseNavigationDrawerItemclasses documentation.Added in version 2.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerMenu(*args, **kwargs)#
Implements a scrollable list for menu items of the
MDNavigationDrawerclass.For more information, see in the
MDScrollViewclass documentation.Added in version 1.0.0.
MDNavigationDrawer: MDNavigationDrawerMenu: # Your menu items. ...
- spacing#
Spacing between children, in pixels.
spacingis aNumericPropertyand 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.
Added 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.
Added in version 1.9.0.
- widget:
>>> 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
MDCardclass documentation.- Events:
Added 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_clickandenable_swipingto prevent closing drawer for standard type.Changed in version 2.0.0: Rename from type to drawer_type.
drawer_typeis aOptionPropertyand defaults to ‘modal’.
- anchor#
Anchoring screen edge for drawer. Set it to ‘right’ for right-to-left languages. Available options are: ‘left’, ‘right’.
anchoris aOptionPropertyand 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_coloris aColorPropertyand 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"
paddingis aVariableListPropertyand 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_clickis aBooleanPropertyand defaults to True.
- state#
Indicates if panel closed or opened. Sets after
statuschange. Available options are: ‘close’, ‘open’.stateis aOptionPropertyand defaults to ‘close’.
- status#
Detailed state. Sets before
state. Bind tostateinstead ofstatus. Available options are: ‘closed’, ‘opening_with_swipe’, ‘opening_with_animation’, ‘opened’, ‘closing_with_swipe’, ‘closing_with_animation’.statusis aOptionPropertyand 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_progressis aNumericPropertyand defaults to 0.0.
- enable_swiping#
Allow to open or close navigation drawer with swipe. It automatically sets to False for “standard” type.
enable_swipingis aBooleanPropertyand defaults to True.
- swipe_distance#
The distance of the swipe with which the movement of navigation drawer begins.
swipe_distanceis aNumericPropertyand defaults to 10.
- swipe_edge_width#
The size of the area in px inside which should start swipe to drag navigation drawer.
swipe_edge_widthis aNumericPropertyand defaults to 20.
- scrim_alpha_transition#
The name of the animation transition type to use for changing
scrim_alpha.scrim_alpha_transitionis aStringPropertyand defaults to ‘linear’.
- opening_transition#
The name of the animation transition type to use when animating to the
state‘open’.opening_transitionis aStringPropertyand defaults to ‘out_cubic’.
- opening_time#
The time taken for the panel to slide to the
state‘open’.opening_timeis aNumericPropertyand defaults to 0.2.
- closing_transition#
The name of the animation transition type to use when animating to the
state‘close’.closing_transitionis aStringPropertyand defaults to ‘out_sine’.
- closing_time#
The time taken for the panel to slide to the
state‘close’.closing_timeis aNumericPropertyand defaults to 0.2.
- background_color#
The drawer background color in (r, g, b, a) or string format.
Added in version 2.0.0.
background_coloris aColorPropertyand defaults to None.
- theme_elevation_level = 'Custom'#
Drawer elevation level scheme name.
Added in version 2.0.0.
Available options are: ‘Primary’, ‘Custom’.
theme_elevation_levelis anOptionPropertyand defaults to ‘Custom’.
- elevation_level = 1#
Drawer elevation level (values from 0 to 5)
Added in version 2.2.0.
elevation_levelis anBoundedNumericPropertyand defaults to 2.
- set_state(new_state='toggle', animation=True) → None#
Change state of the side panel. New_state can be one of “toggle”, “open” or “close”.
- on_touch_down(touch)#
Receive a touch down event.
- Parameters:
- touch:
MotionEventclass Touch received. The touch is in parent coordinates. See
relativelayoutfor a discussion on coordinate systems.
- touch:
- 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
radiusvalue changes.
- on_drawer_type(instance_navigation_drawer, drawer_type: str) → None#
Fired when the
drawer_typevalue changes.