Navigation bar#

#

Bottom navigation bars allow movement between primary destinations in an app:

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

Usage#

<Root>

    MDNavigationBar:

        MDNavigationItem:

            MDNavigationItemIcon:

            MDNavigationItemLabel:

        [...]

Anatomy#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigationbar-item-anatomy.png

Example#

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

from kivymd.app import MDApp
from kivymd.uix.navigationbar import MDNavigationBar, MDNavigationItem
from kivymd.uix.screen import MDScreen


class BaseMDNavigationItem(MDNavigationItem):
    icon = StringProperty()
    text = StringProperty()


class BaseScreen(MDScreen):
    image_size = StringProperty()


KV = '''
<BaseMDNavigationItem>

    MDNavigationItemIcon:
        icon: root.icon

    MDNavigationItemLabel:
        text: root.text


<BaseScreen>

    FitImage:
        source: f"https://picsum.photos/{root.image_size}/{root.image_size}"
        size_hint: .9, .9
        pos_hint: {"center_x": .5, "center_y": .5}
        radius: dp(24)


MDBoxLayout:
    orientation: "vertical"
    md_bg_color: self.theme_cls.backgroundColor

    MDScreenManager:
        id: screen_manager

        BaseScreen:
            name: "Screen 1"
            image_size: "1024"

        BaseScreen:
            name: "Screen 2"
            image_size: "800"

        BaseScreen:
            name: "Screen 3"
            image_size: "600"


    MDNavigationBar:
        on_switch_tabs: app.on_switch_tabs(*args)

        BaseMDNavigationItem
            icon: "gmail"
            text: "Screen 1"
            active: True

        BaseMDNavigationItem
            icon: "twitter"
            text: "Screen 2"

        BaseMDNavigationItem
            icon: "linkedin"
            text: "Screen 3"
'''


class Example(MDApp):
    def on_switch_tabs(
        self,
        bar: MDNavigationBar,
        item: MDNavigationItem,
        item_icon: str,
        item_text: str,
    ):
        self.root.ids.screen_manager.current = item_text

    def build(self):
        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigationbar-usage.gif

API break#

1.2.0 version#

from kivy.lang import Builder

from kivymd.app import MDApp


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

    MDBottomNavigation:

        MDBottomNavigationItem:
            name: 'screen 1'
            text: 'Mail'
            icon: 'gmail'
            badge_icon: "numeric-10"

            MDLabel:
                text: 'Screen 1'
                halign: 'center'

        MDBottomNavigationItem:
            name: 'screen 2'
            text: 'Twitter'
            icon: 'twitter'

            MDLabel:
                text: 'Screen 2'
                halign: 'center'
'''
        )


Example().run()

2.0.0 version#

MDNavigationBar in version 2.0.0 no longer provides a screen manager for content placement. You have to implement it yourself. This is due to the fact that when using MDNavigationBar and MDTabs widgets at the same time, there were conflicts between their screen managers.

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

from kivymd.app import MDApp
from kivymd.uix.navigationbar import MDNavigationBar, MDNavigationItem
from kivymd.uix.screen import MDScreen


class BaseMDNavigationItem(MDNavigationItem):
    icon = StringProperty()
    text = StringProperty()


class BaseScreen(MDScreen):
    ...


KV = '''
<BaseMDNavigationItem>

    MDNavigationItemIcon:
        icon: root.icon

    MDNavigationItemLabel:
        text: root.text


<BaseScreen>

    MDLabel:
        text: root.name
        halign: "center"


MDBoxLayout:
    orientation: "vertical"
    md_bg_color: self.theme_cls.backgroundColor

    MDScreenManager:
        id: screen_manager

        BaseScreen:
            name: "Screen 1"

        BaseScreen:
            name: "Screen 2"


    MDNavigationBar:
        on_switch_tabs: app.on_switch_tabs(*args)

        BaseMDNavigationItem
            icon: "gmail"
            text: "Screen 1"
            active: True

        BaseMDNavigationItem
            icon: "twitter"
            text: "Screen 2"
'''


class Example(MDApp):
    def on_switch_tabs(
        self,
        bar: MDNavigationBar,
        item: MDNavigationItem,
        item_icon: str,
        item_text: str,
    ):
        self.root.ids.screen_manager.current = item_text

    def build(self):
        return Builder.load_string(KV)


Example().run()

API - kivymd.uix.navigationbar.navigationbar#

class kivymd.uix.navigationbar.navigationbar.MDNavigationItemLabel(*args, **kwargs)#

Implements a text label for the MDNavigationItem class.

Added in version 2.0.0.

For more information, see in the MDLabel class documentation.

text_color_active#

Item icon color in (r, g, b, a) or string format.

text_color_active is a ColorProperty and defaults to None.

text_color_normal#

Item icon color in (r, g, b, a) or string format.

text_color_normal is a ColorProperty and defaults to None.

class kivymd.uix.navigationbar.navigationbar.MDNavigationItemIcon(*args, **kwargs)#

Implements a icon for the MDNavigationItem class.

Added in version 2.0.0.

For more information, see in the MDIcon class documentation.

icon_color_active#

Item icon color in (r, g, b, a) or string format.

icon_color_active is a ColorProperty and defaults to None.

icon_color_normal#

Item icon color in (r, g, b, a) or string format.

icon_color_normal is a ColorProperty and defaults to None.

class kivymd.uix.navigationbar.navigationbar.MDNavigationItem(*args, **kwargs)#

Bottom item class.

For more information, see in the DeclarativeBehavior and RectangularRippleBehavior and AnchorLayout and ButtonBehavior classes documentation.

Changed in version 2.0.0: Rename class from MDBottomNavigationItem to MDNavigationItem.

active#

Indicates if the bar item is active or inactive.

active is a BooleanProperty and defaults to False.

indicator_color#

The background color in (r, g, b, a) or string format of the highlighted item.

Added in version 1.0.0.

Changed in version 2.0.0: Rename property from selected_color_background to indicator_color.

indicator_color is an ColorProperty and defaults to None.

indicator_transition#

Animation type of the active element indicator.

indicator_transition is an StringProperty and defaults to ‘in_out_sine’.

indicator_duration#

Duration of animation of the active element indicator.

indicator_duration is an NumericProperty and defaults to 0.1.

on_active(instance, value) None#

Fired when the values of active change.

on_release() None#

Fired when clicking on a panel 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)
class kivymd.uix.navigationbar.navigationbar.MDNavigationBar(*args, **kwargs)#

A navigation bar class.

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

Events:
on_switch_tabs

Fired when switching tabs.

Added in version 1.0.0.

Changed in version 2.0.0: Rename class from MDBottomNavigation to MDNavigationBar.

set_bars_color#

If True the background color of the navigation bar will be set automatically according to the current color of the toolbar.

Added in version 1.0.0.

set_bars_color is an BooleanProperty and defaults to False.

set_active_item(item: MDNavigationItem) None#

Sets the currently active element on the panel.

set_status_bar_color(interval: int | float) None#

Sets the color of the lower system navigation bar.

on_switch_tabs(item: MDNavigationItem, item_icon: str, item_text: str) None#

Fired when switching tabs.