NavigationRail

New in version 1.0.0.

See also

Material Design spec, Navigation rail

Navigation rails provide access to primary destinations in apps when using tablet and desktop screens.

Usage

Declarative KV styleDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDBoxLayout:

    MDNavigationRail:

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

        MDNavigationRailItem:
            text: "JavaScript"
            icon: "language-javascript"

        MDNavigationRailItem:
            text: "CPP"
            icon: "language-cpp"

        MDNavigationRailItem:
            text: "Git"
            icon: "git"

    MDScreen:
'''


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


Example().run()

Anatomy

1. Container

2. Label text (optional)

3. Icon

4. Active indicator

5. Badge (optional)

6. Large badge (optional)

7. Large badge label (optional)

8. Menu icon (optional)

Example

Declarative KV and imperative python stylesDeclarative python style

from kivy.clock import Clock
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.button import MDFillRoundFlatIconButton
from kivymd.uix.label import MDLabel
from kivymd.uix.screen import MDScreen

KV = '''
#:import FadeTransition kivy.uix.screenmanager.FadeTransition


<ExtendedButton>
    elevation: 1
    shadow_radius: 12
    -height: "56dp"


<DrawerClickableItem@MDNavigationDrawerItem>
    focus_color: "#e7e4c0"
    unfocus_color: "#fffcf4"


MDScreen:

    MDNavigationLayout:

        ScreenManager:

            MDScreen:

                MDBoxLayout:
                    orientation: "vertical"

                    MDBoxLayout:
                        adaptive_height: True
                        md_bg_color: "#fffcf4"
                        padding: "12dp"

                        MDLabel:
                            text: "12:00"
                            adaptive_height: True
                            pos_hint: {"center_y": .5}

                    MDBoxLayout:

                        MDNavigationRail:
                            id: navigation_rail
                            md_bg_color: "#fffcf4"
                            selected_color_background: "#e7e4c0"
                            ripple_color_item: "#e7e4c0"
                            on_item_release: app.switch_screen(*args)

                            MDNavigationRailMenuButton:
                                on_release: nav_drawer.set_state("open")

                            MDNavigationRailFabButton:
                                md_bg_color: "#b0f0d6"

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

                            MDNavigationRailItem:
                                text: "JavaScript"
                                icon: "language-javascript"

                            MDNavigationRailItem:
                                text: "CPP"
                                icon: "language-cpp"

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

                        ScreenManager:
                            id: screen_manager
                            transition:
                                FadeTransition(duration=.2, clearcolor=app.theme_cls.bg_dark)

    MDNavigationDrawer:
        id: nav_drawer
        radius: 0, 16, 16, 0
        md_bg_color: "#fffcf4"
        elevation: 2
        width: "240dp"

        MDNavigationDrawerMenu:

            MDBoxLayout:
                orientation: "vertical"
                adaptive_height: True
                spacing: "12dp"
                padding: 0, 0, 0, "12dp"

                MDIconButton:
                    icon: "menu"

                MDBoxLayout:
                    adaptive_height: True
                    padding: "12dp", 0, 0, 0

                    ExtendedButton:
                        text: "Compose"
                        icon: "pencil"

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

            DrawerClickableItem:
                text: "JavaScript"
                icon: "language-javascript"

            DrawerClickableItem:
                text: "CPP"
                icon: "language-cpp"

            DrawerClickableItem:
                text: "Swift"
                icon: "language-swift"
'''


class ExtendedButton(MDFillRoundFlatIconButton, CommonElevationBehavior):
    '''
    Implements a button of type
    `Extended FAB <https://m3.material.io/components/extended-fab/overview>`_.

    .. rubric::
        Extended FABs help people take primary actions.
        They're wider than FABs to accommodate a text label and larger target
        area.

    This type of buttons is not yet implemented in the standard widget set
    of the KivyMD library, so we will implement it ourselves in this class.
    '''

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.padding = "16dp"
        Clock.schedule_once(self.set_spacing)

    def set_spacing(self, interval):
        self.ids.box.spacing = "12dp"

    def set_radius(self, *args):
        if self.rounded_button:
            value = self.height / 4
            self.radius = [value, value, value, value]
            self._radius = value


class Example(MDApp):
    def build(self):
        self.theme_cls.material_style = "M3"
        self.theme_cls.primary_palette = "Orange"
        return Builder.load_string(KV)

    def switch_screen(
        self, instance_navigation_rail, instance_navigation_rail_item
    ):
        '''
        Called when tapping on rail menu items. Switches application screens.
        '''

        self.root.ids.screen_manager.current = (
            instance_navigation_rail_item.icon.split("-")[1].lower()
        )

    def on_start(self):
        '''Creates application screens.'''

        navigation_rail_items = self.root.ids.navigation_rail.get_items()[:]
        navigation_rail_items.reverse()

        for widget in navigation_rail_items:
            name_screen = widget.icon.split("-")[1].lower()
            screen = MDScreen(
                name=name_screen,
                md_bg_color="#edd769",
                radius=[18, 0, 0, 0],
            )
            box = MDBoxLayout(padding="12dp")
            label = MDLabel(
                text=name_screen.capitalize(),
                font_style="H1",
                halign="right",
                adaptive_height=True,
                shorten=True,
            )
            box.add_widget(label)
            screen.add_widget(box)
            self.root.ids.screen_manager.add_widget(screen)


Example().run()

API - kivymd.uix.navigationrail.navigationrail

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailFabButton(*args, **kwargs)

Implements an optional floating action button (FAB).

For more information, see in the MDFloatingActionButton class documentation.

icon

Button icon name.

MDNavigationRail:

    MDNavigationRailFabButton:
        icon: "home"

icon is an StringProperty and defaults to ‘pencil’.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailMenuButton(*args, **kwargs)

Implements a menu button.

For more information, see in the MDIconButton classes documentation.

icon

Button icon name.

MDNavigationRail:

    MDNavigationRailMenuButton:
        icon: "home"

icon is an StringProperty and defaults to ‘menu’.

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

Implements a menu item with an icon and text.

For more information, see in the ButtonBehavior and MDBoxLayout classes documentation.

navigation_rail

MDNavigationRail object.

navigation_rail is an ObjectProperty and defaults to None.

icon

Icon item.

MDNavigationRail:

    MDNavigationRailItem:
        icon: "language-python"

icon is an StringProperty and defaults to ‘checkbox-blank’.

text

Text item.

MDNavigationRail:

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

text is an StringProperty and defaults to ‘’.

badge_icon

Badge icon name.

MDNavigationRail:

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

badge_icon is an StringProperty and defaults to ‘’.

badge_icon_color

Badge icon color in (r, g, b, a) format.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        badge_icon: "plus"
        badge_icon_color: 0, 0, 1, 1

badge_icon_color is an StringProperty and defaults to None.

badge_bg_color

Badge icon background color in (r, g, b, a) format.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        badge_icon: "plus"
        badge_bg_color: "#b0f0d6"

badge_bg_color is an ColorProperty and defaults to None.

badge_font_size

Badge icon font size.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        badge_icon: "plus"
        badge_font_size: "24sp"

badge_font_size is an NumericProperty and defaults to 0.

active

Is the element active.

active is an BooleanProperty and defaults to False.

on_active(self, instance_navigation_rail_item, value_active: bool)

Called when the value of active changes.

animation_size_ripple_area(self, value: int)

Animates the size/fade of the ripple area.

on_press(self)

Called when pressed on a panel element.

on_release(self)

Called when released on a panel element.

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

Navigation rail class.

For more information, see in the MDCard class documentation.

Events:

on_item_press

Called on the on_press event of menu item - MDNavigationRailItem.

on_item_release

Called on the on_release event of menu item - MDNavigationRailItem.

radius

Rail radius.

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

padding

Padding between layout box and children: [padding_left, padding_top, padding_right, padding_bottom].

padding is a VariableListProperty and defaults to [0, ‘36dp’, 0, ‘36dp’].

anchor

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

Top

MDNavigationRail:
    anchor: "top"

    MDNavigationRailItem:
        ...

Center

MDNavigationRail:
    anchor: "center"

    MDNavigationRailItem:
        ...

Bottom

MDNavigationRail:
    anchor: "bottom"

    MDNavigationRailItem:
        ...

anchor is an OptionProperty and defaults to ‘top’.

type

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

Labeled

MDNavigationRail:
    type: "labeled"

    MDNavigationRailItem:
        ...

Selected

MDNavigationRail:
    type: "selected"

    MDNavigationRailItem:
        ...

Unselected

MDNavigationRail:
    type: "unselected"

    MDNavigationRailItem:
        ...

type is an OptionProperty and defaults to ‘labeled’.

text_color_item_normal

The text color in (r, g, b, a) or string format of the normal menu item (MDNavigationRailItem).

MDNavigationRail:
    text_color_item_normal: app.theme_cls.primary_color

    MDNavigationRailItem:
        ...

text_color_item_normal is an ColorProperty and defaults to None.

text_color_item_active

The text color in (r, g, b, a) or string format of the active menu item (MDNavigationRailItem).

MDNavigationRail:
    text_color_item_active: app.theme_cls.primary_color

    MDNavigationRailItem:
        ...

text_color_item_active is an ColorProperty and defaults to None.

icon_color_item_normal

The icon color in (r, g, b, a) or string format of the normal menu item (MDNavigationRailItem).

MDNavigationRail:
    icon_color_item_normal: app.theme_cls.primary_color

    MDNavigationRailItem:
        ...

icon_color_item_normal is an ColorProperty and defaults to None.

icon_color_item_active

The icon color in (r, g, b, a) or string format of the active menu item (MDNavigationRailItem).

MDNavigationRail:
    icon_color_item_active: app.theme_cls.primary_color

    MDNavigationRailItem:
        ...

icon_color_item_active is an ColorProperty and defaults to None.

selected_color_background

Background color which will highlight the icon of the active menu item - MDNavigationRailItem - in (r, g, b, a) format.

MDNavigationRail:
    selected_color_background: "#e7e4c0"

    MDNavigationRailItem:
        ...

selected_color_background is an ColorProperty and defaults to None.

ripple_color_item

Ripple effect color of menu items (MDNavigationRailItem) in (r, g, b, a) format.

MDNavigationRail:
    ripple_color_item: "#e7e4c0"

    MDNavigationRailItem:
        ...

ripple_color_item is an ColorProperty and defaults to None.

ripple_transition

Type of animation of the ripple effect when a menu item is selected.

ripple_transition is a StringProperty and defaults to ‘ripple_transition’.

current_selected_item

Index of the menu list item (MDNavigationRailItem) that will be active by default

MDNavigationRail:
    current_selected_item: 1

    MDNavigationRailItem:
        ...

current_selected_item is a NumericProperty and defaults to 0.

font_name

Font path for menu item (MDNavigationRailItem) text.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        font_name: "nasalization-rg.ttf"

font_name is an StringProperty and defaults to ‘Roboto’.

on_size(self, *args)

on_item_press(self, *args)

Called on the on_press event of menu item - MDNavigationRailItem.

on_item_release(self, *args)

Called on the on_release event of menu item - MDNavigationRailItem.

deselect_item(self, selected_navigation_rail_item: MDNavigationRailItem)

Sets the active value to False for all menu items (MDNavigationRailItem) except the selected item. Called when a menu item is touched.

get_items(self)

Returns a list of MDNavigationRailItem objects

set_pos_panel_items(self, instance_fab_button: None | MDNavigationRailFabButton, instance_menu_button: None | MDNavigationRailFabButton)

Set Paneltems panel position with menu items.

set_current_selected_item(self, interval: int | float)

Sets the active menu list item (MDNavigationRailItem).

set_pos_menu_fab_buttons(self, *args)

Sets the position of the MDNavigationRailFabButton and MDNavigationRailMenuButton buttons on the panel.

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