Appbar

See also

Material Design spec, App bars: top

Material Design spec, App bars: bottom

KivyMD provides the following bar positions for use:

• TopAppBar

• BottomAppBar

TopAppBar

• Contains a title and actions related to the current screen

• Four types: center-aligned, small, medium, and large

• On scroll, apply a container fill color to separate app bar from body content

• Top app bars have the same width as the device window

1. Center-aligned

2. Small

3. Medium

4. Large

Note

KivyMD does not provide a Center-aligned type panel. But you can easily create this pit panel yourself (read the documentation below).

Usage

MDTopAppBar:
    type: "small"

    MDTopAppBarLeadingButtonContainer:

        MDActionTopAppBarButton:
            icon: "menu"

    MDTopAppBarTitle:
        text: "AppBar Center-aligned"
        pos_hint: {"center_x": .5}

    MDTopAppBarTrailingButtonContainer:

        MDActionTopAppBarButton:
            icon: "account-circle-outline"

Anatomy

Configurations

1. Center-aligned

MDScreen:
    md_bg_color: self.theme_cls.secondaryContainerColor

    MDTopAppBar:
        type: "small"
        size_hint_x: .8
        pos_hint: {"center_x": .5, "center_y": .5}

        MDTopAppBarLeadingButtonContainer:

            MDActionTopAppBarButton:
                icon: "menu"

        MDTopAppBarTitle:
            text: "AppBar small"
            pos_hint: {"center_x": .5}

        MDTopAppBarTrailingButtonContainer:

            MDActionTopAppBarButton:
                icon: "account-circle-outline"

2. Small

MDScreen:
    md_bg_color: self.theme_cls.secondaryContainerColor

    MDTopAppBar:
        type: "small"
        size_hint_x: .8
        pos_hint: {"center_x": .5, "center_y": .5}

        MDTopAppBarLeadingButtonContainer:

            MDActionTopAppBarButton:
                icon: "arrow-left"

        MDTopAppBarTitle:
            text: "AppBar small"

        MDTopAppBarTrailingButtonContainer:

            MDActionTopAppBarButton:
                icon: "attachment"

            MDActionTopAppBarButton:
                icon: "calendar"

            MDActionTopAppBarButton:
                icon: "dots-vertical"

3. Medium

MDTopAppBar:
    type: "medium"

4. Large

MDTopAppBar:
    type: "large"

BottomAppBar

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBottomAppBar:

        MDFabBottomAppBarButton:
            icon: "plus"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()

Add action items

#:import MDActionBottomAppBarButton kivymd.uix.appbar.MDActionBottomAppBarButton


MDScreen:

    MDBottomAppBar:
        action_items:
            [
            MDActionBottomAppBarButton(icon="gmail"),
            MDActionBottomAppBarButton(icon="label-outline"),
            MDActionBottomAppBarButton(icon="bookmark"),
            ]

Change action items

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.appbar import MDActionBottomAppBarButton

KV = '''
#:import MDActionBottomAppBarButton kivymd.uix.appbar.MDActionBottomAppBarButton


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBottomAppBar:
        id: bottom_appbar
        action_items:
            [
            MDActionBottomAppBarButton(icon="gmail"),
            MDActionBottomAppBarButton(icon="bookmark"),
            ]

        MDFabBottomAppBarButton:
            icon: "plus"
            on_release: app.change_actions_items()
'''


class Example(MDApp):
    def change_actions_items(self):
        self.root.ids.bottom_appbar.action_items = [
            MDActionBottomAppBarButton(icon="magnify"),
            MDActionBottomAppBarButton(icon="trash-can-outline"),
            MDActionBottomAppBarButton(icon="download-box-outline"),
        ]

    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()

A practical example

import asynckivy

from kivy.clock import Clock
from kivy.lang import Builder
from kivy.properties import StringProperty, BooleanProperty, ObjectProperty
from kivy.uix.behaviors import FocusBehavior
from kivy.uix.recycleboxlayout import RecycleBoxLayout
from kivy.uix.recycleview.layout import LayoutSelectionBehavior
from kivy.uix.recycleview.views import RecycleDataViewBehavior

from kivymd.uix.appbar import MDActionBottomAppBarButton
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.app import MDApp

from faker import Faker  # pip install Faker

KV = '''
#:import MDFabBottomAppBarButton kivymd.uix.appbar.MDFabBottomAppBarButton


<UserCard>
    orientation: "vertical"
    adaptive_height: True
    md_bg_color: "#373A22" if self.selected else "#1F1E15"
    radius: 16
    padding: 0, 0, 0, "16dp"

    MDListItem:
        theme_bg_color: "Custom"
        md_bg_color: root.md_bg_color
        radius: root.radius
        ripple_effect: False

        MDListItemLeadingAvatar:
            source: root.avatar
            # radius: self.height / 2

        MDListItemHeadlineText:
            text: root.name
            theme_text_color: "Custom"
            text_color: "#8A8D79"

        MDListItemSupportingText:
            text: root.time
            theme_text_color: "Custom"
            text_color: "#8A8D79"

    MDLabel:
        text: root.text
        adaptive_height: True
        theme_text_color: "Custom"
        text_color: "#8A8D79"
        padding_x: "16dp"
        shorten: True
        shorten_from: "right"

    Widget:


MDFloatLayout:
    md_bg_color: "#151511"

    RecycleView:
        id: card_list
        viewclass: "UserCard"

        SelectableRecycleGridLayout:
            orientation: 'vertical'
            spacing: "16dp"
            padding: "16dp"
            default_size: None, dp(120)
            default_size_hint: 1, None
            size_hint_y: None
            height: self.minimum_height
            multiselect: True
            touch_multiselect: True

    MDBottomAppBar:
        id: bottom_appbar
        scroll_cls: card_list
        allow_hidden: True
        theme_bg_color: "Custom"
        md_bg_color: "#232217"

        MDFabBottomAppBarButton:
            id: fab_button
            icon: "plus"
            theme_bg_color: "Custom"
            md_bg_color: "#373A22"
            theme_icon_color: "Custom"
            icon_color: "#ffffff"
'''


class UserCard(RecycleDataViewBehavior, MDBoxLayout):
    name = StringProperty()
    time = StringProperty()
    text = StringProperty()
    avatar = StringProperty()
    callback = ObjectProperty(lambda x: x)

    index = None
    selected = BooleanProperty(False)
    selectable = BooleanProperty(True)

    def refresh_view_attrs(self, rv, index, data):
        self.index = index
        return super().refresh_view_attrs(rv, index, data)

    def on_touch_down(self, touch):
        if super().on_touch_down(touch):
            return True
        if self.collide_point(*touch.pos) and self.selectable:
            Clock.schedule_once(self.callback)
            return self.parent.select_with_touch(self.index, touch)

    def apply_selection(self, rv, index, is_selected):
        self.selected = is_selected
        rv.data[index]["selected"] = is_selected


class SelectableRecycleGridLayout(
    FocusBehavior, LayoutSelectionBehavior, RecycleBoxLayout
):
    pass


class BottomAppBarButton(MDActionBottomAppBarButton):
    theme_icon_color = "Custom"
    icon_color = "#8A8D79"


class Example(MDApp):
    selected_cards = False

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

    def on_tap_card(self, *args):
        datas = [data["selected"] for data in self.root.ids.card_list.data]
        if True in datas and not self.selected_cards:
            self.root.ids.bottom_appbar.action_items = [
                BottomAppBarButton(icon="gmail"),
                BottomAppBarButton(icon="label-outline"),
                BottomAppBarButton(icon="bookmark"),
            ]
            self.root.ids.fab_button.icon = "pencil"
            self.selected_cards = True
        else:
            if len(list(set(datas))) == 1 and not list(set(datas))[0]:
                self.selected_cards = False
            if not self.selected_cards:
                self.root.ids.bottom_appbar.action_items = [
                    BottomAppBarButton(icon="magnify"),
                    BottomAppBarButton(icon="trash-can-outline"),
                    BottomAppBarButton(icon="download-box-outline"),
                ]
                self.root.ids.fab_button.icon = "plus"

    def on_start(self):
        async def generate_card():
            for i in range(10):
                await asynckivy.sleep(0)
                self.root.ids.card_list.data.append(
                    {
                        "name": fake.name(),
                        "time": fake.date(),
                        "avatar": fake.image_url(),
                        "text": fake.text(),
                        "selected": False,
                        "callback": self.on_tap_card,
                    }
                )

        self.on_tap_card()
        fake = Faker()
        Clock.schedule_once(lambda x: asynckivy.start(generate_card()))


Example().run()

API break

1.2.0 version

MDTopAppBar:
    type_height: "large"
    headline_text: "Headline"
    left_action_items: [["arrow-left", lambda x: x]]
    right_action_items:
        [             ["attachment", lambda x: x],             ["calendar", lambda x: x],             ["dots-vertical", lambda x: x],             ]
    anchor_title: "left"

2.0.0 version

MDTopAppBar:
    type: "large"

    MDTopAppBarLeadingButtonContainer:

        MDActionTopAppBarButton:
            icon: "arrow-left"

    MDTopAppBarTitle:
        text: "AppBar small"

    MDTopAppBarTrailingButtonContainer:

        MDActionTopAppBarButton:
            icon: "attachment"

        MDActionTopAppBarButton:
            icon: "calendar"

        MDActionTopAppBarButton:
            icon: "dots-vertical"

API - kivymd.uix.appbar.appbar

class kivymd.uix.appbar.appbar.MDFabBottomAppBarButton(**kwargs)

Implements a floating action button (FAB) for a bar with type ‘bottom’.

For more information, see in the MDFabButton and RotateBehavior and ScaleBehavior and classes documentation.

class kivymd.uix.appbar.appbar.MDActionTopAppBarButton(**kwargs)

Implements action buttons on the bar.

For more information, see in the MDIconButton class documentation.

md_bg_color_disabled

The background color in (r, g, b, a) or string format of the button when the button is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.appbar.appbar.MDActionBottomAppBarButton(**kwargs)

Implements action buttons for a :class:’~kivymd.uix.appbar.appbar.MDBottomAppBar’ class.

New in version 1.2.0.

For more information, see in the MDActionTopAppBarButton class documentation.

class kivymd.uix.appbar.appbar.MDTopAppBarTitle(*args, **kwargs)

Implements the panel title.

New in version 2.0.0.

For more information, see in the MDLabel class documentation.

on_text(instance, value) → None

Fired when the text value changes.

on_pos_hint(instance, value) → None

Fired when the pos_hint value changes.

class kivymd.uix.appbar.appbar.MDTopAppBarLeadingButtonContainer(*args, **kwargs)

Implements a container for the leading action buttons.

New in version 2.0.0.

For more information, see in the DeclarativeBehavior and BoxLayout classes documentation.

class kivymd.uix.appbar.appbar.MDTopAppBarTrailingButtonContainer(*args, **kwargs)

Implements a container for the trailing action buttons.

New in version 2.0.0.

For more information, see in the DeclarativeBehavior and BoxLayout classes documentation.

class kivymd.uix.appbar.appbar.MDTopAppBar(*args, **kwargs)

Top app bar class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and CommonElevationBehavior and BackgroundColorBehavior and BoxLayout and WindowController classes documentation.

Events:

on_action_button

Method for the button used for the MDBottomAppBar class.

set_bars_color

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

New in version 1.0.0.

See set_bars_colors for more information.

set_bars_color is an BooleanProperty and defaults to False.

type

Bar height type.

New in version 1.0.0.

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

type_height is an OptionProperty and defaults to ‘small’.

on_type(instance, value) → None

on_size(instance, size) → None

Fired when the application screen size changes.

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.

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)

class kivymd.uix.appbar.appbar.MDBottomAppBar(*args, **kwargs)

Bottom app bar class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and CommonElevationBehavior and FloatLayout classes documentation.

Events:

on_show_bar

The method is fired when the MDBottomAppBar panel is shown.

on_hide_bar

The method is fired when the MDBottomAppBar panel is hidden.

action_items

The icons on the left bar.

New in version 1.2.0.

action_items is an ListProperty and defaults to [].

animation

# TODO: add description. # FIXME: changing the value does not affect anything.

New in version 1.2.0.

animation is an BooleanProperty and defaults to True.

show_transition

Type of button display transition.

New in version 1.2.0.

show_transition is a StringProperty and defaults to ‘linear’.

hide_transition

Type of button hidden transition.

New in version 1.2.0.

hide_transition is a StringProperty and defaults to ‘in_back’.

hide_duration

Duration of button hidden transition.

New in version 1.2.0.

hide_duration is a NumericProperty and defaults to 0.2.

show_duration

Duration of button display transition.

New in version 1.2.0.

show_duration is a NumericProperty and defaults to 0.2.

scroll_cls

Widget inherited from the ScrollView class. The value must be set if the allow_hidden parameter is True.

New in version 1.2.0.

scroll_cls is a ObjectProperty and defaults to None.

allow_hidden

Allows or disables hiding the panel when scrolling content. If the value is True, the scroll_cls parameter must be specified.

New in version 1.2.0.

allow_hidden is a BooleanProperty and defaults to False.

bar_is_hidden

Is the panel currently hidden.

New in version 1.2.0.

bar_is_hidden is a BooleanProperty and defaults to False.

button_centering_animation(button: MDActionBottomAppBarButton | MDFabBottomAppBarButton) → None

Animation of centering buttons for MDActionOverFlowButton, MDActionBottomAppBarButton and MDFabBottomAppBarButton classes.

check_scroll_direction(scroll_cls, y: float) → None

Checks the scrolling direction. Depending on the scrolling direction, hides or shows the MDBottomAppBar panel.

show_bar() → None

Show MDBottomAppBar panel.

hide_bar() → None

Hide MDBottomAppBar panel.

on_show_bar(*args) → None

The method is fired when the MDBottomAppBar panel is shown.

on_hide_bar(*args) → None

The method is fired when the MDBottomAppBar panel is hidden.

on_scroll_cls(instance, scroll_cls) → None

Fired when the value of the scroll_cls attribute changes.

on_size(*args) → None

Fired when the root screen is resized.

on_action_items(instance, value: list) → None

Fired when the value of the action_items attribute changes.

set_fab_opacity(*ars) → None

Sets the transparency value of the:class:~MDFabBottomAppBarButton button.

set_fab_icon(instance, value) → None

Animates the size of the MDFabBottomAppBarButton button.

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