NavigationRail

Added in version 1.0.0.

See also

Material Design spec, Navigation rail

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

Declarative Python style with KVDeclarative Python style

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

Anatomy

Declarative KV styleDeclarative Python style

MDNavigationRail:

    # Optional.
    MDNavigationRailMenuButton:
        icon: "menu"

    # Optional.
    MDNavigationRailFabButton:
        icon: "home"

    MDNavigationRailItem

        MDNavigationRailItemIcon:
            icon: icon

        MDNavigationRailItemLabel:
            text: text

Anatomy item

Declarative KV styleDeclarative Python style

MDNavigationRailItem

    MDNavigationRailItemIcon:
        icon: icon

    MDNavigationRailItemLabel:
        text: text

Configurations

Rail types

1. Selected

2. Unselected

3. Labeled

Selected

MDNavigationRail:
    type: "selected"  # default

Unselected

MDNavigationRail:
    type: "unselected"

Labeled

MDNavigationRail:
    type: "labeled"

Rail anchored

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

Declarative KV styleDeclarative Python style

MDNavigationRail:

    # Optional.
    MDNavigationRailMenuButton:
        icon: "menu"

    # Optional.
    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 StateFocusBehavior 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 ‘center’.

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)