NavigationRail#

#

Added in version 1.0.0.

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

Navigation rails let people switch between UI views on mid-sized devices.

  • Can contain 3-7 destinations plus an optional FAB

  • Always put the rail in the same place, even on different screens of an app

Example#

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

from kivymd.app import MDApp
from kivymd.uix.navigationrail import MDNavigationRailItem

KV = '''
<CommonNavigationRailItem>

    MDNavigationRailItemIcon:
        icon: root.icon

    MDNavigationRailItemLabel:
        text: root.text


MDBoxLayout:

    MDNavigationRail:
        type: "selected"

        MDNavigationRailMenuButton:
            icon: "menu"

        MDNavigationRailFabButton:
            icon: "home"

        CommonNavigationRailItem:
            icon: "folder-outline"
            text: "Files"

        CommonNavigationRailItem:
            icon: "bookmark-outline"
            text: "Bookmark"

        CommonNavigationRailItem:
            icon: "library-outline"
            text: "Library"

    MDScreen:
        md_bg_color: self.theme_cls.secondaryContainerColor
'''


class CommonNavigationRailItem(MDNavigationRailItem):
    text = StringProperty()
    icon = StringProperty()


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-usage.png

Anatomy#

MDNavigationRail:

    # Optional.
    MDNavigationRailMenuButton:
        icon: "menu"

    # Optional.
    MDNavigationRailFabButton:
        icon: "home"

    MDNavigationRailItem

        MDNavigationRailItemIcon:
            icon: icon

        MDNavigationRailItemLabel:
            text: text

    [...]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-anatomy.png

Anatomy item#

MDNavigationRailItem

    MDNavigationRailItemIcon:
        icon: icon

    MDNavigationRailItemLabel:
        text: text
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-anatomy-item.png

Configurations#

Rail types#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type.png
  1. Selected

  2. Unselected

  3. Labeled

Selected#

MDNavigationRail:
    type: "selected"  # default
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-selected.gif

Unselected#

MDNavigationRail:
    type: "unselected"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-unselected.gif

Labeled#

MDNavigationRail:
    type: "labeled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-labeled.gif

Rail anchored#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-anchored.png
  1. Top

  2. Center

  3. Bottom

Top#

MDNavigationRail:
    anchor: "top"

Center#

MDNavigationRail:
    anchor: "center"  # default

Bottom#

MDNavigationRail:
    anchor: "bottom"

API break#

1.2.0 version#

MDNavigationRail:

    MDNavigationRailMenuButton:
        icon: "menu"

    MDNavigationRailFabButton:
        icon: "home"

    MDNavigationRailItem:
        icon: icon
        text: text

    [...]

2.2.0 version#

MDNavigationRail:

    MDNavigationRailMenuButton:
        icon: "menu"

    MDNavigationRailFabButton:
        icon: "home"

    MDNavigationRailItem

        MDNavigationRailItemIcon:
            icon: icon

        MDNavigationRailItemLabel:
            text: text

    [...]

API - kivymd.uix.navigationrail.navigationrail#

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailFabButton(**kwargs)#

Implements a floating action button (FAB).

For more information, see in the MDFabButton class documentation.

md_bg_color_disabled#

The background color in (r, g, b, a) or string format of the switch when the widget is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailMenuButton(**kwargs)#

Implements a menu button.

For more information, see in the MDIconButton class documentation.

md_bg_color_disabled#

The background color in (r, g, b, a) or string format of the switch when the widget is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailItemIcon(*args, **kwargs)#

Implements an icon for the MDNavigationRailItem class.

For more information, see in the RectangularRippleBehavior and MDIcon classes documentation.

Changed in version 2.0.0.

active_indicator_color#

Background color of the active indicator in (r, g, b, a) or string format.

active_indicator_color is an ColorProperty and defaults to None.

anim_complete(*args)#

Fired when the “fade_out” animation complete.

lay_canvas_instructions() None#

Adds graphic instructions to the canvas to implement ripple animation.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailItemLabel(*args, **kwargs)#

Implements an label for the MDNavigationRailItem class.

For more information, see in the ScaleBehavior and MDLabel classes documentation.

Changed in version 2.0.0.

scale_value_y#

Y-axis value.

scale_value_y is an NumericProperty and defaults to 0.

on__active(instance, value) None#

Fired when the _active value changes.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailItem(*args, **kwargs)#

Implements a menu item with an icon and text.

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

active#

Is the element active.

active is an BooleanProperty and defaults to False.

radius#

Item radius.

Changed in version 2.0.0.

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

on_active(instance, value) None#

Fired when the active value changes.

on_enter(*args) None#

Fired when mouse enter the bbox of the widget.

on_leave(*args) None#

Fired when the mouse goes outside the widget border.

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.

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

Navigation rail class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and RelativeLayout classes documentation.

radius#

Rail radius.

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

anchor#

The position of the panel with menu items. Available options are: ‘top’, ‘bottom’, ‘center’.

anchor is an OptionProperty and defaults to ‘top’.

type#

Type of switching menu items. Available options are: ‘labeled’, ‘selected’, ‘unselected’.

type is an OptionProperty and defaults to ‘labeled’.

fab_button: MDNavigationRailFabButton#
menu_button: MDNavigationRailFabButton#
on_size(*args) None#

Fired when the application screen size changes.

get_items() list#

Returns a list of MDNavigationRailItem objects.

set_active_item(item: MDNavigationRailItem) None#

Sets the active menu list item.

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.

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