Toolbar

See also

Material Design spec, App bars: top

Material Design spec, App bars: bottom

Material Design 3 spec, App bars: bottom

KivyMD provides the following toolbar positions for use:

• Top

• Bottom

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()

Add left menu

MDTopAppBar:
    title: "MDTopAppBar"
    left_action_items: [["menu", lambda x: app.callback()]]

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()]]

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()]]

Change toolbar color

MDTopAppBar:
    title: "MDTopAppBar"
    md_bg_color: app.theme_cls.accent_color

Change toolbar text color

MDTopAppBar:
    title: "MDTopAppBar"
    specific_text_color: app.theme_cls.accent_color

Shadow elevation control

MDTopAppBar:
    title: "Elevation 4"
    elevation: 4

Bottom

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()

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"

MDBottomAppBar:

    MDTopAppBar:
        title: "Title"
        icon: "git"
        type: "bottom"
        left_action_items: [["menu", lambda x: x]]
        mode: "free-end"

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

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()

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"]]

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"],
        ]

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"],
        ]

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"

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"

Mode “free-end”:

MDBottomAppBar:

    MDTopAppBar:
        mode: "free-end"

Mode “free-center”:

MDBottomAppBar:

    MDTopAppBar:
        mode: "free-center"

Mode “center”:

MDBottomAppBar:

    MDTopAppBar:
        mode: "center"

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

MDTopAppBar:
    opposite_colors: True

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

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"],
        ]

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)