BottomNavigation#

See also

Material Design 2 spec, Bottom navigation and Material Design 3 spec, Bottom navigation

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>

    MDBottomNavigation:

        MDBottomNavigationItem:
            name: "screen 1"

            YourContent:

        MDBottomNavigationItem:
            name: "screen 2"

            YourContent:

        MDBottomNavigationItem:
            name: "screen 3"

            YourContent:

For ease of understanding, this code works like this:

<Root>

    ScreenManager:

        Screen:
            name: "screen 1"

            YourContent:

        Screen:
            name: "screen 2"

            YourContent:

        Screen:
            name: "screen 3"

            YourContent:

Example#

from kivy.lang import Builder

from kivymd.app import MDApp


class Test(MDApp):

    def build(self):
        self.theme_cls.material_style = "M3"
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(
            '''
MDScreen:

    MDBottomNavigation:
        #panel_color: "#eeeaea"
        selected_color_background: "orange"
        text_color_active: "lightgrey"

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

            MDLabel:
                text: 'Mail'
                halign: 'center'

        MDBottomNavigationItem:
            name: 'screen 2'
            text: 'Twitter'
            icon: 'twitter'
            badge_icon: "numeric-5"

            MDLabel:
                text: 'Twitter'
                halign: 'center'

        MDBottomNavigationItem:
            name: 'screen 3'
            text: 'LinkedIN'
            icon: 'linkedin'

            MDLabel:
                text: 'LinkedIN'
                halign: 'center'
'''
        )


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation.gif

MDBottomNavigationItem provides the following events for use:

__events__ = (
    "on_tab_touch_down",
    "on_tab_touch_move",
    "on_tab_touch_up",
    "on_tab_press",
    "on_tab_release",
)

Root:

    MDBottomNavigation:

        MDBottomNavigationItem:
            on_tab_touch_down: print("on_tab_touch_down")
            on_tab_touch_move: print("on_tab_touch_move")
            on_tab_touch_up: print("on_tab_touch_up")
            on_tab_press: print("on_tab_press")
            on_tab_release: print("on_tab_release")

            YourContent:

How to automatically switch a tab?#

Use method switch_tab which takes as argument the name of the tab you want to switch to.

Use custom icon#

MDBottomNavigation:

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

API - kivymd.uix.bottomnavigation.bottomnavigation#

class kivymd.uix.bottomnavigation.bottomnavigation.MDTab(*args, **kwargs)#

A tab is simply a screen with meta information that defines the content that goes in the tab header.

text#

Tab header text.

text is an StringProperty and defaults to ‘’.

icon#

Tab header icon.

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

badge_icon#

Tab header badge icon.

New in version 1.0.0.

badge_icon is an StringProperty and defaults to ‘’.

on_tab_touch_down(self, *args)#
on_tab_touch_move(self, *args)#
on_tab_touch_up(self, *args)#
on_tab_press(self, *args)#
on_tab_release(self, *args)#
class kivymd.uix.bottomnavigation.bottomnavigation.MDBottomNavigationItem(*args, **kwargs)#

A tab is simply a screen with meta information that defines the content that goes in the tab header.

header#

header is an MDBottomNavigationHeader and defaults to None.

animate_header(self, bottom_navigation_object, bottom_navigation_header_object)#
on_tab_press(self, *args)#

Called when clicking on a panel item.

on_disabled(self, instance_bottom_navigation_item, disabled_value: bool)#
on_leave(self, *args)#
class kivymd.uix.bottomnavigation.bottomnavigation.TabbedPanelBase(**kwargs)#

A class that contains all variables a TabPannel must have. It is here so I (zingballyhoo) don’t get mad about the TabbedPannels not being DRY.

current#

Current tab name.

current is an StringProperty and defaults to None.

previous_tab#

previous_tab is an MDTab and defaults to None.

panel_color#

Panel color of bottom navigation.

panel_color is an ColorProperty and defaults to None.

tabs#
class kivymd.uix.bottomnavigation.bottomnavigation.MDBottomNavigation(*args, **kwargs)#

A bottom navigation that is implemented by delegating all items to a ScreenManager.

Events:
on_switch_tabs

Called when switching tabs. Returns the object of the tab to be opened.

New in version 1.0.0.

transition#

Transition animation of bottom navigation screen manager.

New in version 1.1.0.

transition is an ObjectProperty and defaults to FadeTransition.

transition_duration#

Duration animation of bottom navigation screen manager.

New in version 1.1.0.

transition_duration is an NumericProperty and defaults to 0.2.

text_color_normal#

Text color of the label when it is not selected.

MDBottomNavigation:
    text_color_normal: 1, 0, 1, 1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation-text_color_normal.png

text_color_normal is an ColorProperty and defaults to [1, 1, 1, 1].

text_color_active#

Text color of the label when it is selected.

MDBottomNavigation:
    text_color_active: 0, 0, 0, 1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation-text_color_active.png

text_color_active is an ColorProperty and defaults to [1, 1, 1, 1].

use_text#

Use text for MDBottomNavigationItem or not. If True, the MDBottomNavigation panel height will be reduced by the text height.

New in version 1.0.0.

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

use_text is an BooleanProperty and defaults to True.

selected_color_background#

The background color of the highlighted item when using Material Design v3.

New in version 1.0.0.

MDBottomNavigation:
    selected_color_background: 0, 0, 1, .4
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation=selected-color-background.png

selected_color_background is an ColorProperty and defaults to None.

font_name#

Font name of the label.

New in version 1.0.0.

MDBottomNavigation:
    font_name: "path/to/font.ttf"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation-font-name.png

font_name is an StringProperty and defaults to ‘Roboto’.

first_widget#

first_widget is an MDBottomNavigationItem and defaults to None.

tab_header#

tab_header is an MDBottomNavigationHeader and defaults to None.

set_bars_color#

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

New in version 1.0.0.

set_bars_color is an BooleanProperty and defaults to False.

widget_index#
set_status_bar_color(self, interval: Union[int, float])#
switch_tab(self, name_tab)#

Switching the tab by name.

refresh_tabs(self, *args)#

Refresh all tabs.

on_font_name(self, instance_bottom_navigation, font_name: str)#
on_selected_color_background(self, instance_bottom_navigation, color: list)#
on_use_text(self, instance_bottom_navigation, use_text_value: bool)#
on_text_color_normal(self, instance_bottom_navigation, color: list)#
on_text_color_active(self, instance_bottom_navigation, color: list)#
on_switch_tabs(self, bottom_navigation_item, name_tab: str)#

Called when switching tabs. Returns the object of the tab to be opened.

on_size(self, *args)#
on_resize(self, instance: Union[WindowSDL, None] = None, width: Union[int, None] = None, do_again: bool = True)#

Called when the application window is resized.

add_widget(self, widget, **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)
remove_widget(self, widget)#

Remove a widget from the children of this widget.

Parameters:
widget: Widget

Widget to remove from our children list.

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