Toolbar#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/app-bar-top.png

KivyMD provides the following toolbar positions for use:

Top#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "MDTopAppBar"

    MDLabel:
        text: "Content"
        halign: "center"
'''


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


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-1.png

Add left menu#

MDTopAppBar:
    title: "MDTopAppBar"
    left_action_items: [["menu", lambda x: app.callback()]]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-2.png

Note

The callback is optional. left_action_items: [["menu"]] would also work for a button that does nothing.

Add right menu#

MDTopAppBar:
    title: "MDTopAppBar"
    right_action_items: [["dots-vertical", lambda x: app.callback()]]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-3.png

Add two item to the right menu#

MDTopAppBar:
    title: "MDTopAppBar"
    right_action_items: [["dots-vertical", lambda x: app.callback_1()], ["clock", lambda x: app.callback_2()]]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-4.png

Change toolbar color#

MDTopAppBar:
    title: "MDTopAppBar"
    md_bg_color: app.theme_cls.accent_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-5.png

Change toolbar text color#

MDTopAppBar:
    title: "MDTopAppBar"
    specific_text_color: app.theme_cls.accent_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-6.png

Shadow elevation control#

MDTopAppBar:
    title: "Elevation 4"
    elevation: 4
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-7.png

Bottom#

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

Usage#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDBoxLayout:

    # Will always be at the bottom of the screen.
    MDBottomAppBar:

        MDTopAppBar:
            title: "Title"
            icon: "git"
            type: "bottom"
            left_action_items: [["menu", lambda x: x]]
'''


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


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-8.png

Event on floating button#

Event on_action_button:

MDBottomAppBar:

    MDTopAppBar:
        title: "Title"
        icon: "git"
        type: "bottom"
        left_action_items: [["menu", lambda x: x]]
        on_action_button: app.callback(self.icon)

Floating button position#

Mode:

  • ’free-end’

  • ’free-center’

  • ’end’

  • ’center’

MDBottomAppBar:

    MDTopAppBar:
        title: "Title"
        icon: "git"
        type: "bottom"
        left_action_items: [["menu", lambda x: x]]
        mode: "end"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-9.png
MDBottomAppBar:

    MDTopAppBar:
        title: "Title"
        icon: "git"
        type: "bottom"
        left_action_items: [["menu", lambda x: x]]
        mode: "free-end"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-10.png

Custom color#

MDBottomAppBar:
    md_bg_color: 0, 1, 0, 1

    MDTopAppBar:
        title: "Title"
        icon: "git"
        type: "bottom"
        left_action_items: [["menu", lambda x: x]]
        icon_color: 0, 1, 0, 1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-11.png

Tooltips#

You can add MDTooltips to the Toolbar icons by ading a text string to the toolbar item, as shown below

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.snackbar import Snackbar

KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "MDTopAppBar"
        left_action_items: [["menu", "This is the navigation"]]
        right_action_items:
            [["dots-vertical", lambda x: app.callback(x), "this is the More Actions"]]

    MDLabel:
        text: "Content"
        halign: "center"
'''


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

    def callback(self, button):
        Snackbar(text="Hello World").open()

Test().run()

Material design 3 style#

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.toolbar import MDTopAppBar

KV = '''
MDScreen:

    MDBoxLayout:
        id: box
        orientation: "vertical"
        spacing: "12dp"
        pos_hint: {"top": 1}
        adaptive_height: True
'''


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

    def on_start(self):
        for type_height in ["medium", "large", "small"]:
            self.root.ids.box.add_widget(
                MDTopAppBar(
                    type_height=type_height,
                    headline_text=f"Headline {type_height.lower()}",
                    md_bg_color="#2d2734",
                    left_action_items=[["arrow-left", lambda x: x]],
                    right_action_items=[
                        ["attachment", lambda x: x],
                        ["calendar", lambda x: x],
                        ["dots-vertical", lambda x: x],
                    ],
                    title="Title" if type_height == "small" else ""
                )
            )


TestNavigationDrawer().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-m3.png

API - kivymd.uix.toolbar.toolbar#

class kivymd.uix.toolbar.toolbar.ActionTopAppBarButton(*args, **kwargs)#

Implements action buttons on the toolbar.

overflow_text#
class kivymd.uix.toolbar.toolbar.MDTopAppBar(**kwargs)#
Events:

on_action_button

Method for the button used for the MDBottomAppBar class.

left_action_items#

The icons on the left of the toolbar. To add one, append a list like the following:

MDTopAppBar:
    left_action_items: ["dots-vertical", callback, "tooltip text", "overflow text"]

icon_name - is a string that corresponds to an icon definition:

MDTopAppBar:
    right_action_items: [["home"]]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-icon.png

callback - is the function called on a touch release event and:

MDTopAppBar:
    right_action_items: [["home", lambda x: app.callback(x)]]
class Test(MDApp):
    def callback(self, instance_action_top_appbar_button):
        print(instance_action_top_appbar_button)

tooltip text - is the text to be displayed in the tooltip:

MDTopAppBar:
    right_action_items:
        [
        ["home", lambda x: app.callback(x), "Home"],
        ["message-star", lambda x: app.callback(x), "Message star"],
        ["message-question", lambda x: app.callback(x), "Message question"],
        ["message-reply", lambda x: app.callback(x), "Message reply"],
        ]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-tooltip-text.gif

overflow text - is the text for menu items (OverFlowMenuItem) of the corresponding action buttons:

MDTopAppBar:
    right_action_items:
        [
        ["home", lambda x: app.callback(x), "", "Home"],
        ["message-star", lambda x: app.callback(x), "", "Message star"],
        ["message-question", lambda x: app.callback(x), "" , "Message question"],
        ["message-reply", lambda x: app.callback(x), "", "Message reply"],
        ]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-overflow-text.png

Both the callback and tooltip text and overflow text are optional but the order must be preserved.

left_action_items is an ListProperty and defaults to [].

right_action_items#

The icons on the left of the toolbar. Works the same way as left_action_items.

right_action_items is an ListProperty and defaults to [].

title#

Text toolbar.

MDTopAppBar:
    title: "MDTopAppBar"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-title.png

title is an StringProperty and defaults to ‘’.

mode#

Floating button position. Only for MDBottomAppBar class. Available options are: ‘free-end’, ‘free-center’, ‘end’, ‘center’.

Mode “end”:

MDBottomAppBar:

    MDTopAppBar:
        title: "Title"
        icon: "git"
        type: "bottom"
        left_action_items: [["menu", lambda x: x]]
        mode: "end"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-9.png

Mode “free-end”:

MDBottomAppBar:

    MDTopAppBar:
        mode: "free-end"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-10.png

Mode “free-center”:

MDBottomAppBar:

    MDTopAppBar:
        mode: "free-center"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-free-center.png

Mode “center”:

MDBottomAppBar:

    MDTopAppBar:
        mode: "center"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-center.png

mode is an OptionProperty and defaults to ‘center’.

type#

When using the MDBottomAppBar class, the parameter type must be set to ‘bottom’:

MDBottomAppBar:

    MDTopAppBar:
        type: "bottom"

Available options are: ‘top’, ‘bottom’.

type is an OptionProperty and defaults to ‘top’.

opposite_colors#

Changes the color of the label to the color opposite to the main theme.

MDTopAppBar:
    opposite_colors: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-opposite-true.png
MDTopAppBar:
    opposite_colors: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-opposite-false.png
md_bg_bottom_color#

The background color in (r, g, b, a) or string format for the toolbar with the bottom mode.

New in version 1.0.0.

MDBottomAppBar:

    MDTopAppBar:
        md_bg_bottom_color: 0, 1, 0, 1
        icon_color: self.md_bg_bottom_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-md-bg-bottom-color.png

md_bg_bottom_color is an ColorProperty and defaults to None.

set_bars_color#

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

New in version 1.0.0.

See set_bars_colors <https://kivymd.readthedocs.io/en/latest/api/kivymd/utils/set_bars_colors/> for more information.

set_bars_color is an BooleanProperty and defaults to False.

use_overflow#

As a top app bar is resized, actions move to the overflow menu from right to left.

New in version 1.0.0.

MDTopAppBar:
    title: "MDTopAppBar"
    use_overflow: True
    right_action_items:
        [
        ["home", lambda x: app.callback(x), "Home", "Home"],
        ["message-star", lambda x: app.callback(x), "Message star", "Message star"],
        ["message-question", lambda x: app.callback(x), "Message question", "Message question"],
        ["message-reply", lambda x: app.callback(x), "Message reply", "Message reply"],
        ]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-use-overflow.gif

use_overflow is an BooleanProperty and defaults to False.

overflow_cls#

Must be an object of the MDDropdownMenu class documentation for more information.

New in version 1.0.0.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu

KV = '''
#:import CustomOverFlowMenu __main__.CustomOverFlowMenu


MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "MDTopAppBar"
        use_overflow: True
        overflow_cls: CustomOverFlowMenu()
        right_action_items:
            [
            ["home", lambda x: app.callback(x), "Home", "Home"],
            ["message-star", lambda x: app.callback(x), "Message star", "Message star"],
            ["message-question", lambda x: app.callback(x), "Message question", "Message question"],
            ["message-reply", lambda x: app.callback(x), "Message reply", "Message reply"],
            ]

    MDLabel:
        text: "Content"
        halign: "center"
'''


class CustomOverFlowMenu(MDDropdownMenu):
    # In this class you can set custom properties for the overflow menu.
    pass


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

    def callback(self, instance_action_top_appbar_button):
        print(instance_action_top_appbar_button)


Test().run()

overflow_cls is an ObjectProperty and defaults to None.

icon#

Floating button. Only for MDBottomAppBar class.

icon is an StringProperty and defaults to ‘android’.

icon_color#

Color in (r, g, b, a) or string format action button. Only for MDBottomAppBar class.

icon_color is an ColorProperty and defaults to [].

anchor_title#

Position toolbar title. Only used with material_style = ‘M3’ Available options are: ‘left’, ‘center’, ‘right’.

anchor_title is an OptionProperty and defaults to None.

headline_text#

Headline text toolbar.

New in version 1.0.0.

headline_text is an StringProperty and defaults to ‘’.

headline_text_color#

Headline text color in (r, g, b, a) or string format.

New in version 1.0.0.

headline_text_color is an ColorProperty and defaults to None.

type_height#

Toolbar height type.

New in version 1.0.0.

Available options are: ‘small’, ‘large’, ‘small’.

type_height is an OptionProperty and defaults to ‘small’.

set_headline_font_style(self, interval: Union[int, float])#
on_width(self, instance_toolbar, width: float)#

Called when the toolbar is resized (size of the application window).

return_action_button_to_toolbar(self)#
remove_overflow_button(self)#

Removes an overflow button to the toolbar.

add_overflow_button(self)#

Adds an overflow button to the toolbar.

overflow_action_button_is_added(self)#

Returns True if at least one action button (:class:`~ActionTopAppBarButton’) on the toolbar is added to the overflow.

add_action_button_to_overflow(self)#

Adds an overflow button to the toolbar.

check_overflow_cls(self, interval: Union[int, float])#

If the user does not set the overflow_cls attribute but uses overflows, the overflow_cls attribute will use the default value.

on_type(self, instance_toolbar, type_value: str)#

Called when the value of the type attribute changes.

on_type_height(self, instance_toolbar, height_type_value: str)#

Called when the value of the type_height attribute changes.

on_action_button(self, *args)#

Method for the button used for the MDBottomAppBar class.

on_overflow_cls(self, instance_toolbar, instance_overflow_cls: MDDropdownMenu)#

Called when the value of the overflow_cls attribute changes.

on_md_bg_color(self, instance_toolbar, color_value: list)#

Called when the value of the md_bg_color attribute changes.

on_left_action_items(self, instance_toolbar, items_value: list)#

Called when the value of the left_action_items attribute changes.

on_right_action_items(self, instance_toolbar, items_value: list)#

Called when the value of the right_action_items attribute changes.

on_icon(self, instance_toolbar, icon_name: str)#

Called when the value of the icon attribute changes.

on_icon_color(self, instance, icon_name: str)#

Called when the value of the icon_color attribute changes.

on_md_bg_bottom_color(self, instance_toolbar, color_value: list)#

Called when the value of the md_bg_bottom_color attribute changes.

on_anchor_title(self, instance_toolbar, anchor_value: str)#

Called when the value of the anchor_title attribute changes.

on_mode(self, instance_toolbar, mode_value: str)#

Called when the value of the made attribute changes.

set_md_bg_color(self, instance_toolbar, color_value: list)#
set_notch(self)#
set_shadow(self, *args)#
get_default_overflow_cls(self)#
update_overflow_menu_items(self, action_button)#
update_bar_height(self, instance_theme_manager, material_style_value: str)#
update_floating_radius(self, interval: Union[int, float])#
update_anchor_title(self, material_style_value: str)#
update_action_bar(self, instance_box_layout, action_bar_items: list)#
update_md_bg_color(self, *args)#
update_action_bar_text_colors(self, *args)#
remove_notch(self)#
remove_shadow(self)#
class kivymd.uix.toolbar.toolbar.MDBottomAppBar(*args, **kwargs)#

Implements the creation and addition of child widgets as declarative programming style.

md_bg_color#

Color toolbar in (r, g, b, a) or string format.

md_bg_color is an ColorProperty and defaults to [0, 0, 0, 0].

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)