Navigation Rail

See also

Material Design spec, Navigation rail

Navigation rails provide ergonomic movement between primary destinations in apps.

Usage

MDNavigationRail:

    MDNavigationRailItem:

    MDNavigationRailItem:

    MDNavigationRailItem:

from kivy.factory import Factory
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
#:import get_color_from_hex kivy.utils.get_color_from_hex


<MyTile@SmartTileWithStar>
    size_hint_y: None
    height: "240dp"


MDBoxLayout:
    orientation: "vertical"

    MDToolbar:
        title: "MDNavigationRail"
        md_bg_color: rail.md_bg_color

    MDBoxLayout:

        MDNavigationRail:
            id: rail
            md_bg_color: get_color_from_hex("#344954")
            color_normal: get_color_from_hex("#718089")
            color_active: get_color_from_hex("#f3ab44")

            MDNavigationRailItem:
                icon: "language-cpp"
                text: "C++"

            MDNavigationRailItem:
                icon: "language-python"
                text: "Python"

            MDNavigationRailItem:
                icon: "language-swift"
                text: "Swift"

        MDBoxLayout:
            padding: "24dp"

            ScrollView:

                MDList:
                    id: box
                    cols: 3
                    spacing: "12dp"
'''


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

    def on_start(self):
        for i in range(9):
            tile = Factory.MyTile(source="cpp.png")
            tile.stars = 5
            self.root.ids.box.add_widget(tile)


Test().run()

API - kivymd.uix.navigationrail

class kivymd.uix.navigationrail.MDNavigationRail(**kwargs)

Events

on_item_switch

Called when the menu item is switched.

on_open

Called when a rail is opened.

on_close

Called when a rail is closed.

on_action_button

use_hover_behavior

Whether to use the HoverBehavior effect for menu items.

MDNavigationRail:
    use_hover_behavior: True
    hover_bg: 0, 0, 0, .2

use_hover_behavior is an BooleanProperty and defaults to False.

hover_bg

The background color for the menu item. Used when use_hover_behavior parameter is True.

use_resizeable

Allows you to change the width of the rail (open/close).

from kivy.factory import Factory
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
#:import get_color_from_hex kivy.utils.get_color_from_hex


<MyTile@SmartTileWithStar>
    size_hint_y: None
    height: "240dp"


MDBoxLayout:
    orientation: "vertical"

    MDToolbar:
        title: "MDNavigationRail"
        md_bg_color: rail.md_bg_color
        left_action_items: [["menu", lambda x: app.rail_open()]]

    MDBoxLayout:

        MDNavigationRail:
            id: rail
            md_bg_color: get_color_from_hex("#344954")
            color_normal: get_color_from_hex("#718089")
            color_active: get_color_from_hex("#f3ab44")
            use_resizeable: True

            MDNavigationRailItem:
                icon: "language-cpp"
                text: "C++"

            MDNavigationRailItem:
                icon: "language-java"
                text: "Java"

            MDNavigationRailItem:
                icon: "language-swift"
                text: "Swift"

        MDBoxLayout:
            padding: "24dp"

            ScrollView:

                MDList:
                    id: box
                    cols: 3
                    spacing: "12dp"
'''


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

    def rail_open(self):
        if self.root.ids.rail.rail_state == "open":
            self.root.ids.rail.rail_state = "close"
        else:
            self.root.ids.rail.rail_state = "open"

    def on_start(self):
        for i in range(9):
            tile = Factory.MyTile(source="kitten.png")
            tile.stars = 5
            self.root.ids.box.add_widget(tile)


Test().run()

use_resizeable is an BooleanProperty and defaults to False.

use_title

Whether to use an additional panel at the top of the rail.

MDNavigationRail:
    use_resizeable: True
    use_title: True
    icon_title: "logo.png"
    text_title: "[b][color=#ffffff]Example[/color][/b]"

use_title is an BooleanProperty and defaults to False.

icon_title

Icon (name or path to png file) for NavigationRailTitle class.

icon_title is an StringProperty and defaults to ‘menu’.

text_title

Text title for NavigationRailTitle class.

text_title is an StringProperty and defaults to ‘Rail’.

use_action_button

Should MDFloatingActionButton button be used.

MDNavigationRail:
    use_action_button: True
    action_text_button: "COMPOSE"
    on_action_button: print(args)

use_action_button is an BooleanProperty and defaults to False.

action_icon_button

Icon of use_action_button.

action_icon_button is an StringProperty and defaults to ‘plus’.

action_text_button

Text of use_action_button.

action_text_button is an StringProperty and defaults to ‘’.

action_color_button

Text of use_action_button.

action_color_button is an ColorProperty and defaults to None.

color_normal

Color normal of item menu.

color_normal is an ColorProperty and defaults to None.

color_active

Color active of item menu.

color_active is an ColorProperty and defaults to None.

visible

Item label visible type. Available options are: ‘Selected’, ‘Persistent’, ‘Unlabeled’.

MDNavigationRail:
    visible: "Persistent"

MDNavigationRail:
    visible: "Selected"

MDNavigationRail:
    visible: "Unlabeled"

visible is an OptionProperty and defaults to ‘Persistent’.

color_transition

Animation type when changing the color of a menu item.

color_transition is a StringProperty and defaults to ‘linear’.

color_change_duration

Animation duration when changing menu item color.

color_change_duration is a NumericProperty and defaults to 0.2.

rail_state

Closed or open rails.

rail_state is a OptionProperty and defaults to ‘close’.

anim_color_normal(self, item)

anim_color_active(self, item)

item_switch(self, instance_item)

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

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)

open(self)

close(self)

on_rail_state(self, instance, value)

on_item_switch(self, instance_item)

Called when the menu item is switched.

on_open(self)

Called when a rail is opened.

on_close(self)

Called when a rail is closed.

on_action_button(self, floating_action_button)

Called when the MDFloatingActionButton is pressed.

on_visible(self, instance, value)

on_use_title(self, instance, value)

on_use_resizeable(self, instance, value)

on_use_action_button(self, instance, value)

press_floating_action_button(self, floating_action_button)

set_action_color_button(self, interval)

set_width(self, interval)

set_box_title_size(self, interval)

set_action_icon_button(self, interval)

set_action_text_button(self, interval)

set_color_menu_item(self, instance_item)

set_items_color(self, interval)

set_items_visible(self, interval)