Welcome to KivyMD’s documentation!#

KivyMD#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/previous.png

Is a collection of Material Design compliant widgets for use with, Kivy cross-platform graphical framework a framework for cross-platform, touch-enabled graphical applications. The project’s goal is to approximate Google’s Material Design spec as close as possible without sacrificing ease of use.

This library is a fork of the KivyMD project. We found the strength and brought this project to a new level.

If you wish to become a project developer (permission to create branches on the project without forking for easier collaboration), have at least one PR approved and ask for it. If you contribute regularly to the project the role may be offered to you without asking too.

Contents#

Getting Started#

In order to start using KivyMD, you must first install the Kivy framework on your computer. Once you have installed Kivy, you can install KivyMD.

Warning

KivyMD depends on Kivy! Therefore, before using KivyMD, first learn how to work with Kivy.

Installation#

pip install kivymd

Command above will install latest release version of KivyMD from PyPI. If you want to install development version from master branch, you should specify link to zip archive:

Note

Replace master.zip with <commit hash>.zip (eg 51b8ef0.zip) to download KivyMD from specific commit.

Also you can install manually from sources. Just clone the project and run pip:

git clone https://github.com/kivymd/KivyMD.git --depth 1
cd KivyMD
pip install .

Note

If you don’t need full commit history (about 320 MiB), you can use a shallow clone (git clone https://github.com/kivymd/KivyMD.git –depth 1) to save time. If you need full commit history, then remove –depth 1.

First KivyMD application#

from kivymd.app import MDApp
from kivymd.uix.label import MDLabel


class MainApp(MDApp):
    def build(self):
        return MDLabel(text="Hello, World", halign="center")


MainApp().run()

And the equivalent with Kivy:

from kivy.app import App
from kivy.uix.label import Label


class MainApp(App):
    def build(self):
        return Label(text="Hello, World")


MainApp().run()

To left - Kivy, to right - KivyMD:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hello-world.png

At first glance, the KivyMD example contains more code… However, the following example already demonstrates how difficult it is to create a custom button in Kivy:

from kivy.app import App
from kivy.metrics import dp
from kivy.uix.behaviors import TouchRippleBehavior
from kivy.uix.button import Button
from kivy.lang import Builder
from kivy.utils import get_color_from_hex

KV = """
#:import get_color_from_hex kivy.utils.get_color_from_hex


<RectangleFlatButton>:
    ripple_color: 0, 0, 0, .2
    background_color: 0, 0, 0, 0
    color: root.primary_color

    canvas.before:
        Color:
            rgba: root.primary_color
        Line:
            width: 1
            rectangle: (self.x, self.y, self.width, self.height)

Screen:
    canvas:
        Color:
            rgba: get_color_from_hex("#0F0F0F")
        Rectangle:
            pos: self.pos
            size: self.size
"""


class RectangleFlatButton(TouchRippleBehavior, Button):
    primary_color = get_color_from_hex("#EB8933")

    def on_touch_down(self, touch):
        collide_point = self.collide_point(touch.x, touch.y)
        if collide_point:
            touch.grab(self)
            self.ripple_show(touch)
            return True
        return False

    def on_touch_up(self, touch):
        if touch.grab_current is self:
            touch.ungrab(self)
            self.ripple_fade()
            return True
        return False


class MainApp(App):
    def build(self):
        screen = Builder.load_string(KV)
        screen.add_widget(
            RectangleFlatButton(
                text="Hello, World",
                pos_hint={"center_x": 0.5, "center_y": 0.5},
                size_hint=(None, None),
                size=(dp(110), dp(35)),
                ripple_color=(0.8, 0.8, 0.8, 0.5),
            )
        )
        return screen


MainApp().run()

And the equivalent with KivyMD:

from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen
from kivymd.uix.button import MDButton, MDButtonText


class MainApp(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"

        return (
            MDScreen(
                MDButton(
                    MDButtonText(
                        text="Hello, World",
                    ),
                    pos_hint={"center_x": 0.5, "center_y": 0.5},
                )
            )
        )


MainApp().run()

KivyMD:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/kivymd-ripple-rectangle-button.gif

Kivy:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/kivy-ripple-rectangle-button.gif

Themes#

Theming#

#
Material App#

The main class of your application, which in Kivy inherits from the App class, in KivyMD must inherit from the MDApp class. The MDApp class has properties that allow you to control application properties such as color/style/font of interface elements and much more.

Control material properties#

The main application class inherited from the MDApp class has the theme_cls attribute, with which you control the material properties of your application.

API - kivymd.theming#
class kivymd.theming.ThemeManager(**kwargs)#

Dynamic color class.

New in version 2.0.0.

primary_palette#

The name of the color scheme that the application will use. All major material components will have the color of the specified color theme.

See kivy.utils.hex_colormap keys for available values.

To change the color scheme of an application:

from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDButton:
        style: "elevated"
        pos_hint: {"center_x": .5, "center_y": .5}

        MDButtonIcon:
            icon: "plus"

        MDButtonText:
            text: "Button"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Olive"  # "Purple", "Red"
        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/primary-palette-m3.png

primary_palette is an OptionProperty and defaults to None.

dynamic_color_quality#

The quality of the generated color scheme from the system wallpaper. It is equal to or higher than 1, with 1 representing the maximum quality.

Warning

Remember that by increasing the quality value, you also increase the generation time of the color scheme.

dynamic_color_quality is an NumericProperty and defaults to 10 if platform is not Android else 1.

dynamic_color#

Enables or disables dynamic color.

New in version 2.0.0.

To build the color scheme of your application from user wallpapers, you must enable the READ_EXTERNAL_STORAGE permission if your android version is below 8.1:

from kivy import platform
from kivy.lang import Builder
from kivy.clock import Clock

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.surfaceColor

    MDButton:
        style: "elevated"
        pos_hint: {"center_x": .5, "center_y": .5}

        MDButtonIcon:
            icon: "plus"

        MDButtonText:
            text: "Elevated"
'''


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

    def on_resume(self, *args):
        '''Updating the color scheme when the application resumes.'''

        self.theme_cls.set_colors()

    def set_dynamic_color(self, *args) -> None:
        '''
        When sets the `dynamic_color` value, the self method will be
        `called.theme_cls.set_colors()` which will generate a color
        scheme from a custom wallpaper if `dynamic_color` is `True`.
        '''

        self.theme_cls.dynamic_color = True

    def on_start(self) -> None:
        '''
        It is fired at the start of the application and requests the
        necessary permissions.
        '''

        def callback(permission, results):
            if all([res for res in results]):
                Clock.schedule_once(self.set_dynamic_color)

        super().on_start()
        if platform == "android":
            from android.permissions import Permission, request_permissions

            permissions = [Permission.READ_EXTERNAL_STORAGE]
            request_permissions(permissions, callback)


Example().run()

dynamic_color is an BooleanProperty and defaults to False.

dynamic_scheme_name#

Name of the dynamic scheme. Availabe schemes TONAL_SPOT, SPRITZ VIBRANT, EXPRESSIVE, FRUIT_SALAD, RAINBOW, MONOCHROME, FIDELITY and CONTENT.

dynamic_scheme_name is an OptionProperty and defaults to ‘TONAL_SPOT’.

dynamic_scheme_contrast#

The contrast of the generated color scheme.

dynamic_scheme_contrast is an NumericProperty and defaults to 0.0.

path_to_wallpaper#

The path to the image to set the color scheme. You can use this option if you want to use dynamic color on platforms other than the Android platform.

New in version 2.0.0.

path_to_wallpaper is an StringProperty and defaults to ‘’.

theme_style_switch_animation#

Animate app colors when switching app color scheme (‘Dark/light’).

New in version 1.1.0.

from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDCard:
        orientation: "vertical"
        padding: 0, 0, 0 , "36dp"
        size_hint: .5, .5
        style: "elevated"
        pos_hint: {"center_x": .5, "center_y": .5}

        MDLabel:
            text: "Theme style - {}".format(app.theme_cls.theme_style)
            halign: "center"
            valign: "center"
            bold: True
            font_style: "Display"
            role: "small"

        MDButton:
            on_release: app.switch_theme_style()
            pos_hint: {"center_x": .5}

            MDButtonText:
                text: "Set theme"
'''


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

    def switch_theme_style(self):
        self.theme_cls.primary_palette = (
            "Orange" if self.theme_cls.primary_palette == "Red" else "Red"
        )
        self.theme_cls.theme_style = (
            "Dark" if self.theme_cls.theme_style == "Light" else "Light"
        )


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/theme-style-switch-animation.gif

theme_style_switch_animation is an BooleanProperty and defaults to True.

theme_style_switch_animation_duration#

Duration of the animation of switching the color scheme of the application (“Dark/light”).

New in version 1.1.0.

class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style_switch_animation = True
        self.theme_cls.theme_style_switch_animation_duration = 0.8
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/theme-style-switch-animation-duration.gif

theme_style_switch_animation_duration is an NumericProperty and defaults to 0.2.

theme_style#

App theme style.

from kivy.clock import Clock

from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen
from kivymd.uix.button import MDButton, MDButtonText


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Light"  # "Dark"
        return MDScreen(
            MDButton(
                MDButtonText(
                    text="Hello, World",
                ),
                style="outlined",
                pos_hint={"center_x": 0.5, "center_y": 0.5},
            )
        )

    def on_start(self):
        def on_start(*args):
            self.root.md_bg_color = self.theme_cls.backgroundColor

        super().on_start()
        Clock.schedule_once(on_start)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/theme-style.png

theme_style is an OptionProperty and defaults to ‘Light’.

disabled_hint_text_color#

Color of the disabled text used in the MDTextField.

disabled_hint_text_color is an AliasProperty that returns the value in rgba format for disabled_hint_text_color, property is readonly.

device_orientation#

Device orientation.

device_orientation is an StringProperty and defaults to ‘’.

font_styles#

Data of default font styles.

Add custom font#
from kivy.core.text import LabelBase
from kivy.lang import Builder
from kivy.metrics import sp

from kivymd.app import MDApp

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

    MDLabel:
        text: "MDLabel"
        halign: "center"
        font_style: "nasalization"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"

        LabelBase.register(
            name="nasalization",
            fn_regular="nasalization.ttf",
        )

        self.theme_cls.font_styles["nasalization"] = {
            "large": {
                "line-height": 1.64,
                "font-name": "nasalization",
                "font-size": sp(57),
            },
            "medium": {
                "line-height": 1.52,
                "font-name": "nasalization",
                "font-size": sp(45),
            },
            "small": {
                "line-height": 1.44,
                "font-name": "nasalization",
                "font-size": sp(36),
            },
        }

        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/custom-font-styles.png

font_styles is an DictProperty.

on_colors#

A Helper function called when colors are changed.

Attr:

on_colors defaults to None.

set_colors(*args) None#

Fired methods for setting a new color scheme.

update_theme_colors(*args) None#

Fired when the theme_style value changes.

on_dynamic_scheme_name(*args)#
on_dynamic_scheme_contrast(*args)#
on_path_to_wallpaper(*args)#
switch_theme() None#

Switches the theme from light to dark.

sync_theme_styles(*args) None#
class kivymd.theming.ThemableBehavior(**kwargs)#
theme_cls#

Instance of ThemeManager class.

theme_cls is an ObjectProperty.

device_ios#

True if device is iOS.

device_ios is an BooleanProperty.

theme_line_color#

Line color scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_line_color is an OptionProperty and defaults to ‘Primary’.

theme_bg_color#

Background color scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_bg_color is an OptionProperty and defaults to ‘Primary’.

theme_shadow_color#

Elevation color scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_shadow_color is an OptionProperty and defaults to ‘Primary’.

theme_shadow_offset#

Elevation offset scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_shadow_offset is an OptionProperty and defaults to ‘Primary’.

theme_elevation_level#

Elevation level scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_elevation_level is an OptionProperty and defaults to ‘Primary’.

theme_font_size#

Font size scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_font_size is an OptionProperty and defaults to ‘Primary’.

theme_width#

Widget width scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_width is an OptionProperty and defaults to ‘Primary’.

theme_height#

Widget width scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_height is an OptionProperty and defaults to ‘Primary’.

theme_line_height#

Line height scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_line_height is an OptionProperty and defaults to ‘Primary’.

theme_font_name#

Font name scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_font_name is an OptionProperty and defaults to ‘Primary’.

theme_shadow_softness#

Elevation softness scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_shadow_softness is an OptionProperty and defaults to ‘Primary’.

theme_focus_color#

Focus color scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_focus_color is an OptionProperty and defaults to ‘Primary’.

theme_divider_color#

Divider color scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_divider_color is an OptionProperty and defaults to ‘Primary’.

theme_text_color#

Label color scheme name.

Available options are: ‘Primary’, ‘Secondary’, ‘Hint’, ‘Error’, ‘Custom’.

theme_text_color is an OptionProperty and defaults to ‘Primary’.

theme_icon_color#

Label color scheme name.

Available options are: ‘Primary’, ‘Secondary’, ‘Hint’, ‘Error’, ‘Custom’.

theme_icon_color is an OptionProperty and defaults to ‘Primary’.

remove_widget(widget) None#

Material App#

#

This module contains MDApp class that is inherited from App. MDApp has some properties needed for KivyMD library (like theme_cls). You can turn on the monitor displaying the current FP value in your application:

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

    MDLabel:
        text: "Hello, World!"
        halign: "center"
'''

from kivy.lang import Builder

from kivymd.app import MDApp


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

    def on_start(self):
        super().on_start()
        self.fps_monitor_start()


MainApp().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fps-monitor-dark.png

Note

Note that if you override the built-in on_start method, you will definitely need to call the super method:

class MainApp(MDApp):
    def build(self):
        [...]

    def on_start(self):
        super().on_start()
        [...]
API - kivymd.app#
class kivymd.app.MDApp(**kwargs)#

Application class, see App class documentation for more information.

icon#

See icon attribute for more information.

New in version 1.1.0.

icon is an StringProperty adn default to kivymd/images/logo/kivymd-icon-512.png.

theme_cls#

Instance of ThemeManager class.

Warning

The theme_cls attribute is already available in a class that is inherited from the MDApp class. The following code will result in an error!

class MainApp(MDApp):
    theme_cls = ThemeManager()
    theme_cls.primary_palette = "Teal"

Note

Correctly do as shown below!

class MainApp(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Teal"

theme_cls is an ObjectProperty.

on_start()#

Event handler for the on_start event which is fired after initialization (after build() has been called) but before the application has started running.

New in version 2.0.0.

load_all_kv_files(path_to_directory: str) None#

Recursively loads KV files from the selected directory.

New in version 1.0.0.

Icon Definitions#

#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/material-m3-icons.png

List of icons from materialdesignicons.com. These expanded material design icons are maintained by Austin Andrews (Templarian on Github).

Version 7.4.47

To preview the icons and their names, you can use the following application:#
from kivy.lang import Builder
from kivy.properties import StringProperty

from kivymd.icon_definitions import md_icons
from kivymd.uix.screen import MDScreen
from kivymd.app import MDApp
from kivymd.uix.list import MDListItem

Builder.load_string(
    '''
#:import images_path kivymd.images_path


<IconItem>

    MDListItemLeadingIcon:
        icon: root.icon

    MDListItemSupportingText:
        text: root.text


<PreviousMDIcons>
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        orientation: 'vertical'
        spacing: dp(10)
        padding: dp(20)

        MDBoxLayout:
            adaptive_height: True

            MDIconButton:
                icon: 'magnify'
                pos_hint: {'center_y': .5}

            MDTextField:
                id: search_field
                hint_text: 'Search icon'
                on_text: root.set_list_md_icons(self.text, True)

        RecycleView:
            id: rv
            key_viewclass: 'viewclass'
            key_size: 'height'

            RecycleBoxLayout:
                padding: dp(10), dp(10), 0, dp(10)
                default_size: None, dp(48)
                default_size_hint: 1, None
                size_hint_y: None
                height: self.minimum_height
                orientation: 'vertical'
'''
)


class IconItem(MDListItem):
    icon = StringProperty()
    text = StringProperty()


class PreviousMDIcons(MDScreen):
    def set_list_md_icons(self, text="", search=False):
        '''Builds a list of icons for the screen MDIcons.'''

        def add_icon_item(name_icon):
            self.ids.rv.data.append(
                {
                    "viewclass": "IconItem",
                    "icon": name_icon,
                    "text": name_icon,
                    "callback": lambda x: x,
                }
            )

        self.ids.rv.data = []
        for name_icon in md_icons.keys():
            if search:
                if text in name_icon:
                    add_icon_item(name_icon)
            else:
                add_icon_item(name_icon)


class MainApp(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = PreviousMDIcons()

    def build(self):
        return self.screen

    def on_start(self):
        super().on_start()
        self.screen.set_list_md_icons()


MainApp().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/m3-icons-previous.gif
API - kivymd.icon_definitions#
kivymd.icon_definitions.md_icons#
class kivymd.icon_definitions.IconItem(*args, **kwargs)#

Implements a list item.

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

icon#
text#

Font definitions#

#
API - kivymd.font_definitions#
kivymd.font_definitions.fonts#
kivymd.font_definitions.theme_font_styles#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/label-font-style-preview.png

Components#

Dynamic color#

#

Dynamic color can create accessible UI color schemes based on content or user settings

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dynamic-color.png

Dynamic color experiences are built with M3 color schemes. Beginning with Android 12, users can generate individualized schemes through wallpaper selection and other customization settings. With M3 as a foundation, user-generated colors can coexist with app colors, putting a range of customizable visual experiences in the hands of users.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dynamic-color-preview.png
  1. Baseline scheme

  2. Colors extracted from a wallpaper

  3. Colors extracted from content

Example of dynamic color from the list of standard color schemes#
from kivy.clock import Clock
from kivy.lang import Builder
from kivy.properties import StringProperty, ColorProperty
from kivy.uix.boxlayout import BoxLayout
from kivy.utils import hex_colormap

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


KV = '''
<ColorCard>
    orientation: "vertical"

    MDLabel:
        text: root.text
        color: "grey"
        adaptive_height: True

    MDCard:
        theme_bg_color: "Custom"
        md_bg_color: root.bg_color


MDScreen:
    md_bg_color: app.theme_cls.backgroundColor

    MDIconButton:
        on_release: app.open_menu(self)
        pos_hint: {"top": .98}
        x: "12dp"
        icon: "menu"

    MDRecycleView:
        id: card_list
        viewclass: "ColorCard"
        bar_width: 0
        size_hint_y: None
        height: root.height - dp(68)

        RecycleGridLayout:
            cols: 3
            spacing: "16dp"
            padding: "16dp"
            default_size: None, dp(56)
            default_size_hint: 1, None
            size_hint_y: None
            height: self.minimum_height
'''


class ColorCard(BoxLayout):
    text = StringProperty()
    bg_color = ColorProperty()


class Example(MDApp):
    menu: MDDropdownMenu = None

    def build(self):
        self.theme_cls.dynamic_color = True
        return Builder.load_string(KV)

    def get_instance_from_menu(self, name_item):
        index = 0
        rv = self.menu.ids.md_menu
        opts = rv.layout_manager.view_opts
        datas = rv.data[0]

        for data in rv.data:
            if data["text"] == name_item:
                index = rv.data.index(data)
                break

        instance = rv.view_adapter.get_view(
            index, datas, opts[index]["viewclass"]
        )

        return instance

    def open_menu(self, menu_button):
        menu_items = []
        for item, method in {
            "Set palette": lambda: self.set_palette(),
            "Switch theme style": lambda: self.theme_switch(),
        }.items():
            menu_items.append({"text": item, "on_release": method})
        self.menu = MDDropdownMenu(
            caller=menu_button,
            items=menu_items,
        )
        self.menu.open()

    def set_palette(self):
        instance_from_menu = self.get_instance_from_menu("Set palette")
        available_palettes = [
            name_color.capitalize() for name_color in hex_colormap.keys()
        ]

        menu_items = []
        for name_palette in available_palettes:
            menu_items.append(
                {
                    "text": name_palette,
                    "on_release": lambda x=name_palette: self.switch_palette(x),
                }
            )
        MDDropdownMenu(
            caller=instance_from_menu,
            items=menu_items,
        ).open()

    def switch_palette(self, selected_palette):
        self.theme_cls.primary_palette = selected_palette
        Clock.schedule_once(self.generate_cards, 0.5)

    def theme_switch(self) -> None:
        self.theme_cls.switch_theme()
        Clock.schedule_once(self.generate_cards, 0.5)

    def generate_cards(self, *args):
        self.root.ids.card_list.data = []
        for color in self.theme_cls.schemes_name_colors:
            value = f"{color}Color"
            self.root.ids.card_list.data.append(
                {
                    "bg_color": getattr(self.theme_cls, value),
                    "text": value,
                }
            )

    def on_start(self):
        super().on_start()
        Clock.schedule_once(self.generate_cards)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dynamic-color.gif
Example of a dynamic color from an image#
import os

from kivy.clock import Clock
from kivy.core.window import Window
from kivy.core.window.window_sdl2 import WindowSDL
from kivy.lang import Builder
from kivy.properties import StringProperty, ColorProperty

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


KV = '''
<ColorCard>
    orientation: "vertical"

    MDLabel:
        text: root.text
        color: "grey"
        adaptive_height: True

    MDCard:
        theme_bg_color: "Custom"
        md_bg_color: root.bg_color


MDScreen:
    md_bg_color: app.theme_cls.backgroundColor

    MDRecycleView:
        id: card_list
        viewclass: "ColorCard"
        bar_width: 0

        RecycleGridLayout:
            cols: 3
            spacing: "16dp"
            padding: "16dp"
            default_size: None, dp(56)
            default_size_hint: 1, None
            size_hint_y: None
            height: self.minimum_height
'''


class ColorCard(MDBoxLayout):
    text = StringProperty()
    bg_color = ColorProperty()


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        Window.bind(on_dropfile=self.on_drop_file)

    def on_drop_file(self, sdl: WindowSDL, path_to_file: str) -> None:
        ext = os.path.splitext(path_to_file)[1]
        if isinstance(path_to_file, bytes):
            path_to_file = path_to_file.decode()
        if isinstance(ext, bytes):
            ext = ext.decode()
        if ext in [".png", ".jpg"]:
            self.theme_cls.path_to_wallpaper = path_to_file
            Clock.schedule_once(self.generate_cards, 0.5)

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

    def theme_switch(self) -> None:
        self.theme_cls.switch_theme()
        Clock.schedule_once(self.generate_cards, 0.5)

    def generate_cards(self, *args):
        self.root.ids.card_list.data = []
        for color in self.theme_cls.schemes_name_colors:
            value = f"{color}Color"
            self.root.ids.card_list.data.append(
                {
                    "bg_color": getattr(self.theme_cls, value),
                    "text": value,
                }
            )

    def on_start(self):
        super().on_start()
        Clock.schedule_once(self.generate_cards)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dynamic-color-path-to_wallpapper.gif
API - kivymd.dynamic_color#
class kivymd.dynamic_color.DynamicColor#

Dynamic color class.

New in version 2.0.0.

primaryColor#

Primary color.

primaryColor is an ColorProperty and defaults to None.

primaryContainerColor#

Primary container color.

primaryContainerColor is an ColorProperty and defaults to None.

onPrimaryColor#

On primary color.

onPrimaryColor is an ColorProperty and defaults to None.

onPrimaryContainerColor#

On primary container color.

onPrimaryContainerColor is an ColorProperty and defaults to None.

secondaryColor#

Secondary color.

secondaryColor is an ColorProperty and defaults to None.

secondaryContainerColor#

Secondary container color.

secondaryContainerColor is an ColorProperty and defaults to None.

onSecondaryColor#

On secondary color.

onSecondaryColor is an ColorProperty and defaults to None.

onSecondaryContainerColor#

On secondary container color.

onSecondaryContainerColor is an ColorProperty and defaults to None.

tertiaryColor#

Tertiary color.

tertiaryColor is an ColorProperty and defaults to None.

tertiaryContainerColor#

Tertiary container color.

tertiaryContainerColor is an ColorProperty and defaults to None.

onTertiaryColor#

On tertiary color.

onTertiaryColor is an ColorProperty and defaults to None.

onTertiaryContainerColor#

On tertiary container color.

onTertiaryContainerColor is an ColorProperty and defaults to None.

surfaceColor#

Surface color.

surfaceColor is an ColorProperty and defaults to None.

surfaceDimColor#

Surface dim color.

surfaceDimColor is an ColorProperty and defaults to None.

surfaceBrightColor#

Surface bright color.

surfaceBrightColor is an ColorProperty and defaults to None.

surfaceContainerLowestColor#

Surface container lowest color.

surfaceContainerLowestColor is an ColorProperty and defaults to None.

surfaceContainerLowColor#

Surface container low color.

surfaceContainerLowColor is an ColorProperty and defaults to None.

surfaceContainerColor#

Surface container color.

surfaceContainerColor is an ColorProperty and defaults to None.

surfaceContainerHighColor#

Surface container high color.

surfaceContainerHighColor is an ColorProperty and defaults to None.

surfaceContainerHighestColor#

Surface container highest color.

surfaceContainerHighestColor is an ColorProperty and defaults to None.

surfaceVariantColor#

Surface variant color.

surfaceVariantColor is an ColorProperty and defaults to None.

surfaceTintColor#

Surface tint color.

surfaceTintColor is an ColorProperty and defaults to None.

onSurfaceColor#

On surface color.

onSurfaceColor is an ColorProperty and defaults to None.

onSurfaceLightColor#

On surface light color.

onSurfaceLightColor is an ColorProperty and defaults to None.

onSurfaceVariantColor#

On surface variant color.

onSurfaceVariantColor is an ColorProperty and defaults to None.

inverseSurfaceColor#

Inverse surface color.

inverseSurfaceColor is an ColorProperty and defaults to None.

inverseOnSurfaceColor#

Inverse on surface color.

inverseOnSurfaceColor is an ColorProperty and defaults to None.

inversePrimaryColor#

Inverse primary color.

inversePrimaryColor is an ColorProperty and defaults to None.

backgroundColor#

Background color.

backgroundColor is an ColorProperty and defaults to None.

onBackgroundColor#

On background color.

onBackgroundColor is an ColorProperty and defaults to None.

errorColor#

Error color.

errorColor is an ColorProperty and defaults to None.

errorContainerColor#

Error container color.

errorContainerColor is an ColorProperty and defaults to None.

onErrorColor#

On error color.

onErrorColor is an ColorProperty and defaults to None.

onErrorContainerColor#

On error container color.

onErrorContainerColor is an ColorProperty and defaults to None.

outlineColor#

Outline color.

outlineColor is an ColorProperty and defaults to None.

outlineVariantColor#

Outline variant color.

outlineVariantColor is an ColorProperty and defaults to None.

shadowColor#

Shadow color.

shadowColor is an ColorProperty and defaults to None.

scrimColor#

Scrim color.

scrimColor is an ColorProperty and defaults to None.

disabledTextColor#

Disabled text color.

disabledTextColor is an ColorProperty and defaults to None.

transparentColor#

Transparent color.

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

rippleColor#

Ripple color.

rippleColor is an ColorProperty and defaults to ‘#BDBDBD’.

FloatLayout#

#

FloatLayout class equivalent. Simplifies working with some widget properties. For example:

FloatLayout#
FloatLayout:
    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        RoundedRectangle:
            pos: self.pos
            size: self.size
            radius: [25, 0, 0, 0]
MDFloatLayout#
MDFloatLayout:
    radius: [25, 0, 0, 0]
    md_bg_color: app.theme_cls.primaryColor

Warning

For a FloatLayout, the minimum_size attributes are always 0, so you cannot use adaptive_size and related options.

API - kivymd.uix.floatlayout#
class kivymd.uix.floatlayout.MDFloatLayout(*args, **kwargs)#

Float layout class.

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

GridLayout#

#

GridLayout class equivalent. Simplifies working with some widget properties. For example:

GridLayout#
GridLayout:
    size_hint_y: None
    height: self.minimum_height

    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        Rectangle:
            pos: self.pos
            size: self.size
MDGridLayout#
MDGridLayout:
    adaptive_height: True
    md_bg_color: app.theme_cls.primaryColor
Available options are:#
adaptive_height#
adaptive_height: True

Equivalent

size_hint_y: None
height: self.minimum_height
adaptive_width#
adaptive_width: True

Equivalent

size_hint_x: None
width: self.minimum_width
adaptive_size#
adaptive_size: True

Equivalent

size_hint: None, None
size: self.minimum_size
API - kivymd.uix.gridlayout#
class kivymd.uix.gridlayout.MDGridLayout(*args, **kwargs)#

Grid layout class.

For more information see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and GridLayout and MDAdaptiveWidget classes documentation.

RecycleView#

#

New in version 1.0.0.

RecycleView class equivalent. Simplifies working with some widget properties. For example:

RecycleView#
RecycleView:

    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        Rectangle:
            pos: self.pos
            size: self.size
MDRecycleView#
MDRecycleView:
    md_bg_color: app.theme_cls.primaryColor
API - kivymd.uix.recycleview#
class kivymd.uix.recycleview.MDRecycleView(*args, **kwargs)#

Recycle view class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and RecycleView and MDAdaptiveWidget classes documentation.

ScrollView#

#

New in version 1.0.0.

ScrollView class equivalent. It implements Material Design’s overscorll effect and simplifies working with some widget properties. For example:

ScrollView#
ScrollView:

    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        Rectangle:
            pos: self.pos
            size: self.size
MDScrollView#
MDScrollView:
    md_bg_color: app.theme_cls.primaryColor
API - kivymd.uix.scrollview#
class kivymd.uix.scrollview.StretchOverScrollStencil(*arg, **kwargs)#

Stretches the view on overscroll and absorbs velocity at start and end to convert to stretch. .. note:: This effect only works with kivymd.uix.scrollview.MDScrollView. If you need any documentation please look at dampedscrolleffect.

minimum_absorbed_velocity = 0#
maximum_velocity = 10000#
stretch_intensity = 0.016#
exponential_scalar#
scroll_friction = 0.015#
approx_normailzer = 200000.0#
duration_normailzer = 10#
scroll_view#
scroll_scale#
scale_axis = 'y'#
last_touch_pos#
clamp(value, min_val=0, max_val=0)#
is_top_or_bottom()#
on_value(stencil, scroll_distance)#
get_hw()#
set_scale_origin()#
absorb_impact()#
get_component(pos)#
convert_overscroll(touch)#
reset_scale(*arg)#
class kivymd.uix.scrollview.MDScrollView(*args, **kwargs)#

An approximate implementation to Material Design’s overscorll effect.

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

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_move(touch)#

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)#

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

StackLayout#

#

StackLayout class equivalent. Simplifies working with some widget properties. For example:

StackLayout#
StackLayout:
    size_hint_y: None
    height: self.minimum_height

    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        Rectangle:
            pos: self.pos
            size: self.size
MDStackLayout#
MDStackLayout:
    adaptive_height: True
    md_bg_color: app.theme_cls.primaryColor
Available options are:#
adaptive_height#
adaptive_height: True

Equivalent

size_hint_y: None
height: self.minimum_height
adaptive_width#
adaptive_width: True

Equivalent

size_hint_x: None
width: self.minimum_width
adaptive_size#
adaptive_size: True

Equivalent

size_hint: None, None
size: self.minimum_size
API - kivymd.uix.stacklayout#
class kivymd.uix.stacklayout.MDStackLayout(*args, **kwargs)#

Stack layout class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and StackLayout and MDAdaptiveWidget classes documentation.

RelativeLayout#

#

RelativeLayout class equivalent. Simplifies working with some widget properties. For example:

RelativeLayout#
RelativeLayout:
    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        RoundedRectangle:
            pos: (0, 0)
            size: self.size
            radius: [25, ]
MDRelativeLayout#
MDRelativeLayout:
    radius: [25, ]
    md_bg_color: app.theme_cls.primaryColor
API - kivymd.uix.relativelayout#
class kivymd.uix.relativelayout.MDRelativeLayout(*args, **kwargs)#

Relative layout class.

For more information see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and RelativeLayout and MDAdaptiveWidget classes documentation.

ResponsiveLayout#

#

New in version 1.0.0.

Responsive design is a graphic user interface (GUI) design approach used to create content that adjusts smoothly to various screen sizes.

The MDResponsiveLayout class does not reorganize your UI. Its task is to track the size of the application screen and, depending on this size, the MDResponsiveLayout class selects which UI layout should be displayed at the moment: mobile, tablet or desktop. Therefore, if you want to have a responsive view some kind of layout in your application, you should have three KV files with UI markup for three platforms.

You need to set three parameters for the MDResponsiveLayout class mobile_view, tablet_view and desktop_view. These should be Kivy or KivyMD widgets.

Usage responsive#
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.uix.responsivelayout import MDResponsiveLayout
from kivymd.uix.screen import MDScreen

KV = '''
<CommonComponentLabel>
    halign: "center"


<MobileView>
    CommonComponentLabel:
        text: "Mobile"


<TabletView>
    CommonComponentLabel:
        text: "Table"


<DesktopView>
    CommonComponentLabel:
        text: "Desktop"


ResponsiveView:
'''


class CommonComponentLabel(MDLabel):
    pass


class MobileView(MDScreen):
    pass


class TabletView(MDScreen):
    pass


class DesktopView(MDScreen):
    pass


class ResponsiveView(MDResponsiveLayout, MDScreen):
    def __init__(self, **kw):
        super().__init__(**kw)
        self.mobile_view = MobileView()
        self.tablet_view = TabletView()
        self.desktop_view = DesktopView()


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


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

Note

Use common components for platform layouts (mobile, tablet, desktop views). As shown in the example above, such a common component is the CommonComponentLabel widget.

Perhaps you expected more from the MDResponsiveLayout widget, but even Flutter uses a similar approach to creating a responsive UI.

You can also use the commands provided to you by the developer tools to create a project with an responsive design.

API - kivymd.uix.responsivelayout#
class kivymd.uix.responsivelayout.MDResponsiveLayout(*args, **kwargs)#
Events:
on_change_screen_type

Called when the screen type changes.

mobile_view#

Mobile view. Must be a Kivy or KivyMD widget.

mobile_view is an ObjectProperty and defaults to None.

tablet_view#

Tablet view. Must be a Kivy or KivyMD widget.

tablet_view is an ObjectProperty and defaults to None.

desktop_view#

Desktop view. Must be a Kivy or KivyMD widget.

desktop_view is an ObjectProperty and defaults to None.

on_change_screen_type(*args)#

Called when the screen type changes.

on_size(*args) None#

Called when the application screen size changes.

set_screen() None#

Sets the screen according to the type of application screen size: mobile/tablet or desktop view.

Hero#

#

New in version 1.0.0.

Use the MDHeroFrom widget to animate a widget from one screen to the next.

  • The hero refers to the widget that flies between screens.

  • Create a hero animation using KivyMD’s MDHeroFrom widget.

  • Fly the hero from one screen to another.

  • Animate the transformation of a hero’s shape from circular to rectangular while flying it from one screen to another.

  • The MDHeroFrom widget in KivyMD implements a style of animation commonly known as shared element transitions or shared element animations.

The widget that will move from screen A to screen B will be a hero. To move a widget from one screen to another using hero animation, you need to do the following:

  • On screen A, place the MDHeroFrom container.

  • Sets a tag (string) for the MDHeroFrom container.

  • Place a hero in the MDHeroFrom container.

  • On screen B, place the MDHeroTo container - our hero from screen A will fly into this container.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hero-base.png

Warning

MDHeroFrom container cannot have more than one child widget.

Base example#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreenManager:

    MDScreen:
        name: "screen A"
        md_bg_color: "lightblue"

        MDHeroFrom:
            id: hero_from
            tag: "hero"
            size_hint: None, None
            size: "120dp", "120dp"
            pos_hint: {"top": .98}
            x: 24

            FitImage:
                source: "bg.jpg"
                size_hint: None, None
                size: hero_from.size

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current_heroes = ["hero"]
                root.current = "screen B"

            MDButtonText:
                text: "Move Hero To Screen B"

    MDScreen:
        name: "screen B"
        hero_to: hero_to
        md_bg_color: "cadetblue"

        MDHeroTo:
            id: hero_to
            tag: "hero"
            size_hint: None, None
            size: "220dp", "220dp"
            pos_hint: {"center_x": .5, "center_y": .5}

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current_heroes = ["hero"]
                root.current = "screen A"

            MDButtonText:
                text: "Move Hero To Screen A"
'''


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


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

Note that the child of the MDHeroFrom widget must have the size of the parent:

MDHeroFrom:
    id: hero_from
    tag: "hero"

    FitImage:
        size_hint: None, None
        size: hero_from.size

To enable hero animation before setting the name of the current screen for the screen manager, you must specify the name of the tag of the MDHeroFrom container in which the hero is located:

MDButton:
    on_release:
        root.current_heroes = ["hero"]
        root.current = "screen 2"

    MDButtonText:
        text: "Move Hero To Screen B"

If you need to switch to a screen that does not contain heroes, set the current_hero attribute for the screen manager as “” (empty string):

MDButton:
    on_release:
        root.current_heroes = []
        root.current = "another screen"

    MDButtonText:
        text: "Go To Another Screen"
Example#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreenManager:

    MDScreen:
        name: "screen A"
        md_bg_color: "lightblue"

        MDHeroFrom:
            id: hero_from
            tag: "hero"
            size_hint: None, None
            size: "120dp", "120dp"
            pos_hint: {"top": .98}
            x: 24

            FitImage:
                source: "bg.jpg"
                size_hint: None, None
                size: hero_from.size

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current_heroes = ["hero"]
                root.current = "screen B"

            MDButtonText:
                text: "Move Hero To Screen B"

    MDScreen:
        name: "screen B"
        hero_to: hero_to
        md_bg_color: "cadetblue"

        MDHeroTo:
            id: hero_to
            tag: "hero"
            size_hint: None, None
            size: "220dp", "220dp"
            pos_hint: {"center_x": .5, "center_y": .5}

        MDButton:
            pos_hint: {"center_x": .5}
            y: "52dp"
            on_release:
                root.current_heroes = []
                root.current = "screen C"

            MDButtonText:
                text: "Go To Screen C"

        MDButton:
            pos_hint: {"center_x": .5}
            y: "8dp"
            on_release:
                root.current_heroes = ["hero"]
                root.current = "screen A"

            MDButtonText:
                text: "Move Hero To Screen A"

    MDScreen:
        name: "screen C"
        md_bg_color: "olive"

        MDLabel:
            text: "Screen C"
            halign: "center"

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current = "screen B"

            MDButtonText:
                text: "Back To Screen B"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hero-switch-another-screen.gif
Events#

Two events are available for the hero:

  • on_transform_in - when the hero flies from screen A to screen B.

  • on_transform_out - when the hero back from screen B to screen A.

The on_transform_in, on_transform_out events relate to the MDHeroFrom container. For example, let’s change the radius and background color of the hero during the flight between the screens:

from kivy import utils
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.utils import get_color_from_hex

from kivymd.app import MDApp
from kivymd.uix.hero import MDHeroFrom
from kivymd.uix.relativelayout import MDRelativeLayout

KV = '''
MDScreenManager:

    MDScreen:
        name: "screen A"
        md_bg_color: "lightblue"

        MyHero:
            id: hero_from
            tag: "hero"
            size_hint: None, None
            size: "120dp", "120dp"
            pos_hint: {"top": .98}
            x: 24

            MDRelativeLayout:
                size_hint: None, None
                size: hero_from.size
                md_bg_color: "blue"
                radius: [24, 12, 24, 12]

                FitImage:
                    source: "https://github.com/kivymd/internal/raw/main/logo/kivymd_logo_blue.png"

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current_heroes = ["hero"]
                root.current = "screen B"

            MDButtonText:
                text: "Move Hero To Screen B"

    MDScreen:
        name: "screen B"
        hero_to: hero_to
        md_bg_color: "cadetblue"

        MDHeroTo:
            id: hero_to
            tag: "hero"
            size_hint: None, None
            size: "220dp", "220dp"
            pos_hint: {"center_x": .5, "center_y": .5}

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current_heroes = ["hero"]
                root.current = "screen A"

            MDButtonText:
                text: "Move Hero To Screen A"
'''


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


class MyHero(MDHeroFrom):
    def on_transform_in(
        self, instance_hero_widget: MDRelativeLayout, duration: float
    ):
        '''
        Fired when the hero flies from screen **A** to screen **B**.

        :param instance_hero_widget: dhild widget of the `MDHeroFrom` class.
        :param duration of the transition animation between screens.
        '''

        Animation(
            radius=[12, 24, 12, 24],
            duration=duration,
            md_bg_color=(0, 1, 1, 1),
        ).start(instance_hero_widget)

    def on_transform_out(
        self, instance_hero_widget: MDRelativeLayout, duration: float
    ):
        '''Fired when the hero back from screen **B** to screen **A**.'''

        Animation(
            radius=[24, 12, 24, 12],
            duration=duration,
            md_bg_color=get_color_from_hex(utils.hex_colormap["blue"]),
        ).start(instance_hero_widget)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hero-events.gif
Usage with ScrollView#
from kivy.animation import Animation
from kivy.clock import Clock
from kivy.lang import Builder
from kivy.metrics import dp
from kivy.properties import StringProperty, ObjectProperty

from kivymd.app import MDApp
from kivymd.uix.hero import MDHeroFrom

KV = '''
<HeroItem>
    size_hint_y: None
    height: "200dp"
    radius: "24dp"

    MDSmartTile:
        id: tile
        size_hint: None, None
        size: root.size
        on_release: root.on_release()

        MDSmartTileImage:
            id: image
            source: "bg.jpg"
            radius: dp(24)

        MDSmartTileOverlayContainer:
            id: overlay
            md_bg_color: 0, 0, 0, .5
            adaptive_height: True
            padding: "8dp"
            spacing: "8dp"
            radius: [0, 0, dp(24), dp(24)]

            MDLabel:
                text: root.tag
                theme_text_color: "Custom"
                text_color: "white"
                adaptive_height: True


MDScreenManager:
    md_bg_color: self.theme_cls.backgroundColor

    MDScreen:
        name: "screen A"

        ScrollView:

            MDGridLayout:
                id: box
                cols: 2
                spacing: "12dp"
                padding: "12dp"
                adaptive_height: True

    MDScreen:
        name: "screen B"
        heroes_to: [hero_to]

        MDHeroTo:
            id: hero_to
            size_hint: 1, None
            height: "220dp"
            pos_hint: {"top": 1}

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current_heroes = [hero_to.tag]
                root.current = "screen A"

            MDButtonText:
                text: "Move Hero To Screen A"
'''


class HeroItem(MDHeroFrom):
    text = StringProperty()
    manager = ObjectProperty()

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.ids.image.ripple_duration_in_fast = 0.05

    def on_transform_in(self, instance_hero_widget, duration):
        for instance in [
            instance_hero_widget,
            instance_hero_widget._overlay_container,
            instance_hero_widget._image,
        ]:
            Animation(radius=[0, 0, 0, 0], duration=duration).start(instance)

    def on_transform_out(self, instance_hero_widget, duration):
        for instance, radius in {
            instance_hero_widget: [dp(24), dp(24), dp(24), dp(24)],
            instance_hero_widget._overlay_container: [0, 0, dp(24), dp(24)],
            instance_hero_widget._image: [dp(24), dp(24), dp(24), dp(24)],
        }.items():
            Animation(
                radius=radius,
                duration=duration,
            ).start(instance)

    def on_release(self):
        def switch_screen(*args):
            self.manager.current_heroes = [self.tag]
            self.manager.ids.hero_to.tag = self.tag
            self.manager.current = "screen B"

        Clock.schedule_once(switch_screen, 0.2)


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

    def on_start(self):
        super().on_start()
        for i in range(12):
            hero_item = HeroItem(
                text=f"Item {i + 1}", tag=f"Tag {i}", manager=self.root
            )
            if not i % 2:
                hero_item.md_bg_color = "lightgrey"
            self.root.ids.box.add_widget(hero_item)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hero-usage-with-scrollview.gif
Using multiple heroes at the same time#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreenManager:

    MDScreen:
        name: "screen A"
        md_bg_color: "lightblue"

        MDHeroFrom:
            id: hero_kivymd
            tag: "kivymd"
            size_hint: None, None
            size: "200dp", "200dp"
            pos_hint: {"top": .98}
            x: 24

            FitImage:
                source: "avatar.png"
                size_hint: None, None
                size: hero_kivymd.size
                radius: self.height / 2

        MDHeroFrom:
            id: hero_kivy
            tag: "kivy"
            size_hint: None, None
            size: "200dp", "200dp"
            pos_hint: {"top": .98}
            x: 324

            FitImage:
                source: "bg.jpg"
                size_hint: None, None
                size: hero_kivy.size
                radius: self.height / 2

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current_heroes = ["kivymd", "kivy"]
                root.current = "screen B"

            MDButtonText:
                text: "Move Hero To Screen B"

    MDScreen:
        name: "screen B"
        heroes_to: hero_to_kivymd, hero_to_kivy
        md_bg_color: "cadetblue"

        MDHeroTo:
            id: hero_to_kivy
            tag: "kivy"
            size_hint: None, None
            pos_hint: {"center_x": .5, "center_y": .5}

        MDHeroTo:
            id: hero_to_kivymd
            tag: "kivymd"
            size_hint: None, None
            pos_hint: {"right": 1, "top": 1}

        MDButton:
            pos_hint: {"center_x": .5}
            y: "36dp"
            on_release:
                root.current_heroes = ["kivy", "kivymd"]
                root.current = "screen A"

            MDButtonText:
                text: "Move Hero To Screen A"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hero-multiple-heroes.gif
API - kivymd.uix.hero#
class kivymd.uix.hero.MDHeroFrom(**kwargs)#

The container from which the hero begins his flight.

For more information, see in the MDBoxLayout class documentation.

Events:
on_transform_in

when the hero flies from screen A to screen B.

on_transform_out

Fired when the hero back from screen B to screen A.

tag#

Tag ID for heroes.

tag is an StringProperty and defaults to ‘’.

on_transform_in(*args)#

Fired when the hero flies from screen A to screen B.

on_transform_out(*args)#

Fired when the hero back from screen B to screen A.

class kivymd.uix.hero.MDHeroTo(*args, **kwargs)#

The container in which the hero comes.

For more information, see in the MDBoxLayout class documentation.

tag#

Tag ID for heroes.

tag is an StringProperty and defaults to ‘’.

AnchorLayout#

#

New in version 1.0.0.

AnchorLayout class equivalent. Simplifies working with some widget properties. For example:

AnchorLayout#
AnchorLayout:
    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        Rectangle:
            pos: self.pos
            size: self.size
MDAnchorLayout#
MDAnchorLayout:
    md_bg_color: app.theme_cls.primaryColor
API - kivymd.uix.anchorlayout#
class kivymd.uix.anchorlayout.MDAnchorLayout(*args, **kwargs)#

Anchor layout class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and AnchorLayout and MDAdaptiveWidget classes documentation.

RecycleGridLayout#

#

RecycleGridLayout class equivalent. Simplifies working with some widget properties. For example:

RecycleGridLayout#
RecycleGridLayout:
    size_hint_y: None
    height: self.minimum_height

    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        Rectangle:
            pos: self.pos
            size: self.size
MDRecycleGridLayout#
MDRecycleGridLayout:
    adaptive_height: True
    md_bg_color: app.theme_cls.primaryColor
Available options are:#
adaptive_height#
adaptive_height: True

Equivalent

size_hint_y: None
height: self.minimum_height
adaptive_width#
adaptive_width: True

Equivalent

size_hint_x: None
width: self.minimum_width
adaptive_size#
adaptive_size: True

Equivalent

size_hint: None, None
size: self.minimum_size
API - kivymd.uix.recyclegridlayout#
class kivymd.uix.recyclegridlayout.MDRecycleGridLayout(*args, **kwargs)#

Recycle grid layout class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and RecycleGridLayout and MDAdaptiveWidget classes documentation.

ScreenManager#

#

New in version 1.0.0.

ScreenManager class equivalent. If you want to use Hero animations you need to use MDScreenManager not ScreenManager class.

Transition#

MDScreenManager class supports the following transitions:

  • MDFadeSlideTransition

  • MDSlideTransition

  • MDSwapTransition

You need to use the MDScreenManager class when you want to use hero animations on your screens. If you don’t need hero animation use the ScreenManager class.

API - kivymd.uix.screenmanager#
class kivymd.uix.screenmanager.MDScreenManager(*args, **kwargs)#

Screen manager. This is the main class that will control your MDScreen stack and memory.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and ScreenManager and MDAdaptiveWidget classes documentation.

current_hero#

The name of the current tag for the MDHeroFrom and MDHeroTo objects that will be animated when animating the transition between screens.

Deprecated since version 1.1.0: Use current_heroes attribute instead.

See the Hero module documentation for more information about creating and using Hero animations.

current_hero is an StringProperty and defaults to None.

current_heroes#

A list of names (tags) of heroes that need to be animated when moving to the next screen.

New in version 1.1.0.

current_heroes is an ListProperty and defaults to [].

check_transition(*args) None#

Sets the default type transition.

get_hero_from_widget() list#

Get a list of MDHeroFrom objects according to the tag names specified in the current_heroes list.

on_current_hero(instance, value: str) None#

Fired when the value of the current_hero attribute changes.

add_widget(widget, *args, **kwargs)#

Changed in version 2.1.0: Renamed argument screen to widget.

Widget#

#

Widget class equivalent. Simplifies working with some widget properties. For example:

Widget#
Widget:
    size_hint: .5, None
    height: self.width

    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        RoundedRectangle:
            pos: self.pos
            size: self.size
            radius: [self.height / 2,]
MDWidget#
MDWidget:
    size_hint: .5, None
    height: self.width
    radius: self.height / 2
    md_bg_color: app.theme_cls.primaryColor
API - kivymd.uix.widget#
class kivymd.uix.widget.MDWidget(*args, **kwargs)#

Widget class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and MDAdaptiveWidget and Widget and classes documentation.

New in version 1.0.0.

BoxLayout#

#

BoxLayout class equivalent. Simplifies working with some widget properties. For example:

BoxLayout#
BoxLayout:
    size_hint_y: None
    height: self.minimum_height

    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        Rectangle:
            pos: self.pos
            size: self.size
MDBoxLayout#
MDBoxLayout:
    adaptive_height: True
    md_bg_color: app.theme_cls.primaryColor
Available options are:#
adaptive_height#
adaptive_height: True

Equivalent

size_hint_y: None
height: self.minimum_height
adaptive_width#
adaptive_width: True

Equivalent

size_hint_x: None
height: self.minimum_width
adaptive_size#
adaptive_size: True

Equivalent

size_hint: None, None
size: self.minimum_size
API - kivymd.uix.boxlayout#
class kivymd.uix.boxlayout.MDBoxLayout(*args, **kwargs)#

Box layout class.

For more information see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and BoxLayout and MDAdaptiveWidget classes documentation.

Screen#

#

Screen class equivalent. Simplifies working with some widget properties. For example:

Screen#
Screen:
    canvas:
        Color:
            rgba: app.theme_cls.primaryColor
        RoundedRectangle:
            pos: self.pos
            size: self.size
            radius: [25, 0, 0, 0]
MDScreen#
MDScreen:
    radius: [25, 0, 0, 0]
    md_bg_color: self.theme_cls.primaryColor
API - kivymd.uix.screen#
class kivymd.uix.screen.MDScreen(*args, **kwargs)#

Screen is an element intended to be used with a MDScreenManager.

For more information see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and Screen and MDAdaptiveWidget classes documentation.

hero_to#

Must be a MDHeroTo class.

See the documentation of the MDHeroTo widget for more detailed information.

Deprecated since version 1.0.0: Use attr:heroes_to attribute instead.

hero_to is an ObjectProperty and defaults to None.

heroes_to#

Must be a list of MDHeroTo class.

New in version 1.0.0.

heroes_to is an LiatProperty and defaults to [].

on_hero_to(screen, widget: kivymd.uix.hero.MDHeroTo) None#

Fired when the value of the hero_to attribute changes.

CircularLayout#

#

CircularLayout is a special layout that places widgets around a circle.

MDCircularLayout#

Usage

from kivy.lang.builder import Builder
from kivy.uix.label import Label

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDCircularLayout:
        id: container
        pos_hint: {"center_x": .5, "center_y": .5}
        row_spacing: min(self.size) * 0.1
'''


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

    def on_start(self):
        super().on_start()
        for x in range(1, 49):
            self.root.ids.container.add_widget(Label(text=f"{x}")


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/circular-layout-dark.png
API - kivymd.uix.circularlayout#
class kivymd.uix.circularlayout.MDCircularLayout(**kwargs)#

Float layout class. See module documentation for more information.

degree_spacing#

The space between children in degree.

degree_spacing is an NumericProperty and defaults to 30.

circular_radius#

Radius of circle. Radius will be the greatest value in the layout if circular_radius if not specified.

circular_radius is an NumericProperty and defaults to None.

start_from#

The positon of first child in degree.

start_from is an NumericProperty and defaults to 60.

max_degree#

Maximum range in degree allowed for each row of widgets before jumping to the next row.

max_degree is an NumericProperty and defaults to 360.

circular_padding#

Padding between outer widgets and the edge of the biggest circle.

circular_padding is an NumericProperty and defaults to 25dp.

row_spacing#

Space between each row of widget.

row_spacing is an NumericProperty and defaults to 50dp.

clockwise#

Direction of widgets in circular direction.

clockwise is an BooleanProperty and defaults to True.

get_angle(pos: tuple) float#

Returns the angle of given pos.

remove_widget(widget, **kwargs)#

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)
do_layout(*largs, **kwargs)#

This function is called when a layout is called by a trigger. If you are writing a new Layout subclass, don’t call this function directly but use _trigger_layout() instead.

The function is by default called before the next frame, therefore the layout isn’t updated immediately. Anything depending on the positions of e.g. children should be scheduled for the next frame.

New in version 1.0.8.

Button#

#

Buttons allow users to take actions, and make choices, with a single tap. When choosing the right button for an action, consider the level of emphasis each button type provides.

KivyMD provides the following button classes for use:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/buttons.png
  1. Elevated button

  2. Filled button

  3. Filled tonal button

  4. Outlined button

  5. Text button

  6. Icon button

  7. Segmented button

  8. Floating action button (FAB)

  9. Extended FAB

Common buttons#

Buttons help people take action, such as sending an email, sharing a document, or liking a comment.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/common-buttons.png
  1. Elevated button

  2. Filled button

  3. Filled tonal button

  4. Outlined button

  5. Text button

Elevated Filled Tonal Outlined Text

Elevated#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.surfaceColor

    MDButton:
        style: "elevated"
        pos_hint: {"center_x": .5, "center_y": .5}

        MDButtonIcon:
            icon: "plus"

        MDButtonText:
            text: "Elevated"
'''


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


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

Common buttons can contain an icon or be without an icon:

MDButton:
    style: "elevated"
    text: "Elevated"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/elevated-without-icon-button.png
Filled#
MDButton:
    style: "filled"

    MDButtonText:
        text: "Filled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/filled-button.gif
Tonal#
MDButton:
    style: "tonal"

    MDButtonText:
        text: "Tonal"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tonal-button.gif
Outlined#
MDButton:
    style: "outlined"

    MDButtonText:
        text: "Outlined"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/outlined-button.gif
Text#
MDButton:
    style: "text"

    MDButtonText:
        text: "Text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-button.gif
Customization of buttons#
Text positioning and button size#
MDButton:
    style: "tonal"
    theme_width: "Custom"
    height: "56dp"
    size_hint_x: .5

    MDButtonIcon:
        x: text.x - (self.width + dp(10))
        icon: "plus"

    MDButtonText:
        id: text
        text: "Tonal"
        pos_hint: {"center_x": .5, "center_y": .5}
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/positioning-size-button.png
Font of the button text#
MDButton:
    style: "filled"

    MDButtonIcon:
        icon: "plus"

    MDButtonText:
        text: "Filled"
        font_style: "Title"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/font-style-button-text.png
MDButton:
    style: "elevated"

    MDButtonText:
        text: "Elevated"
        theme_font_name: "Custom"
        font_name: "path/to/font.ttf"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/font-name-button-text.png
Custom button color#
MDButton:
    style: "elevated"
    theme_shadow_color: "Custom"
    shadow_color: "red"

    MDButtonIcon:
        icon: "plus"
        theme_icon_color: "Custom"
        icon_color: "green"

    MDButtonText:
        text: "Elevated"
        theme_text_color: "Custom"
        text_color: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/custom-color-button.png
Icon buttons#

Use icon buttons when a compact button is required, such as in a toolbar or image list. There are two types of icon buttons: standard and contained.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-buttons.png
  1. Standard icon button

  2. Contained icon button (including filled, filled tonal, and outlined styles)

StandardIcon FilledIcon TonalIcon OutlinedIcon

StandardIcon#
MDIconButton:
    icon: "heart-outline"
    style: "standard"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-standard.gif
FilledIcon#
MDIconButton:
    icon: "heart-outline"
    style: "filled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-filled.gif
TonalIcon#
MDIconButton:
    icon: "heart-outline"
    style: "tonal"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-tonal.gif
OutlinedIcon#
MDIconButton:
    icon: "heart-outline"
    style: "outlined"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-outlined.gif
Custom icon size#
MDIconButton:
    icon: "heart-outline"
    style: "tonal"
    theme_font_size: "Custom"
    font_size: "48sp"
    radius: [self.height / 2, ]
    size_hint: None, None
    size: "84dp", "84dp"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-size.png
Custom button color#
MDIconButton:
    icon: "heart-outline"
    style: "tonal"
    theme_bg_color: "Custom"
    md_bg_color: "brown"
    theme_icon_color: "Custom"
    icon_color: "white"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-color.png
FAB buttons#

The FAB represents the most important action on a screen. It puts key actions within reach.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-buttons.png
  1. Standard FAB

  2. Small FAB

  3. Large FAB

There are three sizes of floating action buttons: FAB, small FAB, and large FAB:

Standard Small Large

Standard#
MDFabButton:
    icon: "pencil-outline"
    style: "standard"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-button-standard.gif
Small#
MDFabButton:
    icon: "pencil-outline"
    style: "small"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-button-small.png
Large#
MDFabButton:
    icon: "pencil-outline"
    style: "large"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-button-large.gif
Additional color mappings#

FABs can use other combinations of container and icon colors. The color mappings below provide the same legibility and functionality as the default, so the color mapping you use depends on style alone.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-color-mapping.png
  1. Surface

  2. Secondary

  3. Tertiary

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.button import MDFabButton

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.surfaceColor

    MDBoxLayout:
        id: box
        adaptive_size: True
        spacing: "32dp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


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

    def on_start(self):
        super().on_start()
        styles = {
            "standard": "surface",
            "small": "secondary",
            "large": "tertiary",
        }
        for style in styles.keys():
            self.root.ids.box.add_widget(
                MDFabButton(
                    style=style, icon="pencil-outline", color_map=styles[style]
                )
            )


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-button-color-mapping.png
Extended FAB#

Extended floating action buttons (extended FABs) help people take primary actions. They’re wider than FABs to accommodate a text label and larger target area.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/extended-fab-button.png
  1. Extended FAB with both icon and label text

  2. Extended FAB without icon

With icon#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.surfaceColor
    on_touch_down:
        if not btn.collide_point(*args[1].pos): \
        btn.fab_state = "expand" \
        if btn.fab_state == "collapse" else "collapse"

        MDExtendedFabButton:
            id: btn
            pos_hint: {"center_x": .5, "center_y": .5}

            MDExtendedFabButtonIcon:
                icon: "pencil-outline"

            MDExtendedFabButtonText:
                text: "Compose"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/extended-fab-button-icon.gif
Without icon#
MDExtendedFabButton:
    fab_state: "expand"

    MDExtendedFabButtonText:
        text: "Compose"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/extended-fab-button-without-icon.png
API break#
1.2.0 version#
MDFloatingActionButton:
    icon: "plus"
MDRoundFlatButton:
    text: "Outlined"
MDRoundFlatIconButton:
    text: "Outlined with icon"
    icon: "plus"
MDFillRoundFlatButton
    text: "Filled"
MDFillRoundFlatIconButton
    text: "Filled with icon"
    icon: "plus"
2.0.0 version#

Note

MDFloatingActionButtonSpeedDial type buttons were removed in version 2.0.0.

MDFabButton:
    icon: "plus"
MDButton:
    style: "outlined"

    MDButtonText:
        text: "Outlined"
MDButton:
    style: "outlined"

    MDButtonIcon:
        icon: "plus"

    MDButtonText:
        text: "Outlined with icon"
MDButton:
    style: "filled"

    MDButtonText:
        text: "Filled"
MDButton:
    style: "filled"

    MDButtonIcon:
        icon: "plus"

    MDButtonText:
        text: "Filled"
API - kivymd.uix.button.button#
class kivymd.uix.button.button.BaseFabButton#

Implements the basic properties for the MDExtendedFabButton and MDFabButton classes.

New in version 2.0.0.

elevation_levels#

Elevation is measured as the distance between components along the z-axis in density-independent pixels (dps).

New in version 1.2.0.

elevation_levels is an DictProperty and defaults to {0: dp(0), 1: dp(4), 2: dp(8), 3: dp(12), 4: dp(16), 5: dp(18)}.

color_map#

Additional color mappings.

Available options are: ‘surface’, ‘secondary’, ‘tertiary’.

color_map is an OptionProperty and defaults to ‘secondary’.

icon_color_disabled#

The icon color in (r, g, b, a) or string format of the list item when the widget item is disabled.

icon_color_disabled is a ColorProperty and defaults to None.

style#

Button type.

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

style is an OptionProperty and defaults to ‘standard’.

fab_state#

The state of the button.

Available options are: ‘collapse’ or ‘expand’.

fab_state is an OptionProperty and defaults to “collapse”.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

radius#

Canvas radius.

radius is an VariableListProperty and defaults to [dp(16), dp(16), dp(16), dp(16)].

class kivymd.uix.button.button.BaseButton(*args, **kwargs)#

Base button class.

For more information, see in the DeclarativeBehavior and BackgroundColorBehavior and RectangularRippleBehavior and ButtonBehavior and ThemableBehavior and StateLayerBehavior classes documentation.

elevation_levels#

Elevation is measured as the distance between components along the z-axis in density-independent pixels (dps).

New in version 1.2.0.

elevation_levels is an DictProperty and defaults to {0: dp(0), 1: dp(4), 2: dp(8), 3: dp(12), 4: dp(16), 5: dp(18)}.

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.

shadow_radius#

Button shadow radius.

shadow_radius is an VariableListProperty and defaults to [0, 0, 0, 0].

md_bg_color#

Button background color in (r, g, b, a) or string format.

md_bg_color is a ColorProperty and defaults to None.

line_color#

Outlined color.

line_color is a ColorProperty and defaults to None.

line_width#

Line width for button border.

line_width is a NumericProperty and defaults to 1.

on_press(*args) None#

Fired when the button is pressed.

on_release(*args) None#

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

class kivymd.uix.button.button.MDButton(*args, **kwargs)#

Base class for all buttons.

New in version 2.2.0.

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

style#

Button type.

Available options are: ‘filled’, ‘elevated’, ‘outlined’, ‘tonal’, ‘text’.

style is an OptionProperty and defaults to ‘elevated’.

radius#

Button radius.

radius is an VariableListProperty and defaults to [dp(20), dp(20), dp(20), dp(20)].

adjust_pos(*args) None#

Adjusts the pos of the button according to the content.

adjust_width(*args) None#

Adjusts the width of the button according to the content.

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)
set_properties_widget() None#

Fired on_release/on_press/on_enter/on_leave events.

class kivymd.uix.button.button.MDButtonText(*args, **kwargs)#

The class implements the text for the MDButton class.

For more information, see in the MDLabel class documentation.

class kivymd.uix.button.button.MDButtonIcon(*args, **kwargs)#

The class implements an icon for the MDButton class.

For more information, see in the MDIcon class documentation.

class kivymd.uix.button.button.MDIconButton(**kwargs)#

Base class for icon buttons.

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

style#

Button type.

New in version 2.0.0.

Available options are: ‘standard’, ‘filled’, ‘tonal’, ‘outlined’.

style is an OptionProperty and defaults to ‘standard’.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

on_line_color(instance, value) None#

Fired when the values of line_color change.

class kivymd.uix.button.button.MDFabButton(**kwargs)#

Base class for FAB buttons.

For more information, see in the BaseFabButton and CommonElevationBehavior and RectangularRippleBehavior and ButtonBehavior and MDIcon classes documentation.

on_press(*args) None#

Fired when the button is pressed.

on_release(*args) None#

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

set_properties_widget() None#

Fired on_release/on_press/on_enter/on_leave events.

class kivymd.uix.button.button.MDExtendedFabButtonIcon(*args, **kwargs)#

Implements an icon for the MDExtendedFabButton class.

New in version 2.0.0.

class kivymd.uix.button.button.MDExtendedFabButtonText(*args, **kwargs)#

Implements the text for the class MDExtendedFabButton class.

New in version 2.0.0.

class kivymd.uix.button.button.MDExtendedFabButton(*args, **kwargs)#

Base class for Extended FAB buttons.

New in version 2.0.0.

For more information, see in the DeclarativeBehavior and ThemableBehavior and MotionExtendedFabButtonBehavior and CommonElevationBehavior and StateLayerBehavior and BaseFabButton and ButtonBehavior and RelativeLayout classes documentation.

Events:
on_collapse

Fired when the button is collapsed.

on_expand

Fired when the button is expanded.

elevation_levels#

Elevation is measured as the distance between components along the z-axis in density-independent pixels (dps).

New in version 1.2.0.

elevation_levels is an DictProperty and defaults to {0: dp(0), 1: dp(4), 2: dp(8), 3: dp(12), 4: dp(16), 5: dp(18)}.

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)
on_collapse(*args)#

Fired when the button is collapsed.

on_expand(*args)#

Fired when the button is expanded.

on_fab_state(instance, state: str) None#

Fired when the fab_state value changes.

on__x(instance, value) None#

NavigationDrawer#

#

Navigation drawers provide access to destinations in your app.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer.png
  • Use navigation drawers in expanded layouts and modal navigation drawers in compact and medium layouts

  • Can be open or closed by default

  • Two types: standard and modal

When using the class MDNavigationDrawer skeleton of your KV markup should look like this:

Usage#
Root:

    MDNavigationLayout:

        MDScreenManager:

            Screen_1:

            Screen_2:

        MDNavigationDrawer:

            # This custom rule should implement what will be displayed in
            # your MDNavigationDrawer.
            ContentNavigationDrawer:
A simple example#
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                MDButton:
                    pos_hint: {"center_x": .5, "center_y": .5}
                    on_release: nav_drawer.set_state("toggle")

                    MDButtonText:
                        text: "Open Drawer"

        MDNavigationDrawer:
            id: nav_drawer
            radius: 0, dp(16), dp(16), 0

            MDNavigationDrawerMenu:

                MDNavigationDrawerLabel:
                    text: "Mail"

                MDNavigationDrawerItem:

                    MDNavigationDrawerItemLeadingIcon:
                        icon: "account"

                    MDNavigationDrawerItemText:
                        text: "Inbox"

                    MDNavigationDrawerItemTrailingText:
                        text: "24"

                MDNavigationDrawerDivider:
'''


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


Example().run()
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-anatomy.png

Note

MDNavigationDrawer is an empty MDCard panel.

Item anatomy#
MDNavigationDrawerItem:

    MDNavigationDrawerItemLeadingIcon:
        icon: "account"

    MDNavigationDrawerItemText:
        text: "Inbox"

    MDNavigationDrawerItemTrailingText:
        text: "24"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-item-anatomy.png
Type drawer#
Standard#
MDNavigationDrawer:
    drawer_type: "standard"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-type-standard.gif
Anchoring screen edge for drawer#
MDNavigationDrawer:
    anchor: "left"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-ancjor-left.png
MDNavigationDrawer:
    anchor: "right"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-ancjor-right.png
API break#
1.2.0 version#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<DrawerClickableItem@MDNavigationDrawerItem>
    focus_color: "#e7e4c0"
    text_color: "#4a4939"
    icon_color: "#4a4939"
    ripple_color: "#c5bdd2"
    selected_color: "#0c6c4d"


<DrawerLabelItem@MDNavigationDrawerItem>
    text_color: "#4a4939"
    icon_color: "#4a4939"
    focus_behavior: False
    selected_color: "#4a4939"
    _no_ripple_effect: True


MDScreen:

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                MDRaisedButton:
                    text: "Open Drawer"
                    pos_hint: {"center_x": .5, "center_y": .5}
                    on_release: nav_drawer.set_state("toggle")

        MDNavigationDrawer:
            id: nav_drawer
            radius: (0, dp(16), dp(16), 0)

            MDNavigationDrawerMenu:

                MDNavigationDrawerHeader:
                    title: "Header title"
                    title_color: "#4a4939"
                    text: "Header text"
                    spacing: "4dp"
                    padding: "12dp", 0, 0, "56dp"

                MDNavigationDrawerLabel:
                    text: "Mail"

                DrawerClickableItem:
                    icon: "gmail"
                    right_text: "+99"
                    text_right_color: "#4a4939"
                    text: "Inbox"

                DrawerClickableItem:
                    icon: "send"
                    text: "Outbox"

                MDNavigationDrawerDivider:

                MDNavigationDrawerLabel:
                    text: "Labels"

                DrawerLabelItem:
                    icon: "information-outline"
                    text: "Label"

                DrawerLabelItem:
                    icon: "information-outline"
                    text: "Label"
'''


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


Example().run()
2.2.0 version#
from kivy.lang import Builder
from kivy.properties import StringProperty, ColorProperty

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.navigationdrawer import (
    MDNavigationDrawerItem, MDNavigationDrawerItemTrailingText
)

KV = '''
<DrawerItem>
    active_indicator_color: "#e7e4c0"

    MDNavigationDrawerItemLeadingIcon:
        icon: root.icon
        theme_icon_color: "Custom"
        icon_color: "#4a4939"

    MDNavigationDrawerItemText:
        text: root.text
        theme_text_color: "Custom"
        text_color: "#4a4939"


<DrawerLabel>
    adaptive_height: True
    padding: "18dp", 0, 0, "12dp"

    MDNavigationDrawerItemLeadingIcon:
        icon: root.icon
        theme_icon_color: "Custom"
        icon_color: "#4a4939"
        pos_hint: {"center_y": .5}

    MDNavigationDrawerLabel:
        text: root.text
        theme_text_color: "Custom"
        text_color: "#4a4939"
        pos_hint: {"center_y": .5}
        padding: "6dp", 0, "16dp", 0
        theme_line_height: "Custom"
        line_height: 0


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                MDButton:
                    pos_hint: {"center_x": .5, "center_y": .5}
                    on_release: nav_drawer.set_state("toggle")

                    MDButtonText:
                        text: "Open Drawer"

        MDNavigationDrawer:
            id: nav_drawer
            radius: 0, dp(16), dp(16), 0

            MDNavigationDrawerMenu:

                MDNavigationDrawerHeader:
                    orientation: "vertical"
                    padding: 0, 0, 0, "12dp"
                    adaptive_height: True

                    MDLabel:
                        text: "Header title"
                        theme_text_color: "Custom"
                        theme_line_height: "Custom"
                        line_height: 0
                        text_color: "#4a4939"
                        adaptive_height: True
                        padding_x: "16dp"
                        font_style: "Display"
                        role: "small"

                    MDLabel:
                        text: "Header text"
                        padding_x: "18dp"
                        adaptive_height: True
                        font_style: "Title"
                        role: "large"

                MDNavigationDrawerDivider:

                DrawerItem:
                    icon: "gmail"
                    text: "Inbox"
                    trailing_text: "+99"
                    trailing_text_color: "#4a4939"

                DrawerItem:
                    icon: "send"
                    text: "Outbox"

                MDNavigationDrawerDivider:

                MDNavigationDrawerLabel:
                    text: "Labels"
                    padding_y: "12dp"

                DrawerLabel:
                    icon: "information-outline"
                    text: "Label"

                DrawerLabel:
                    icon: "information-outline"
                    text: "Label"
'''


class DrawerLabel(MDBoxLayout):
    icon = StringProperty()
    text = StringProperty()


class DrawerItem(MDNavigationDrawerItem):
    icon = StringProperty()
    text = StringProperty()
    trailing_text = StringProperty()
    trailing_text_color = ColorProperty()

    _trailing_text_obj = None

    def on_trailing_text(self, instance, value):
        self._trailing_text_obj = MDNavigationDrawerItemTrailingText(
            text=value,
            theme_text_color="Custom",
            text_color=self.trailing_text_color,
        )
        self.add_widget(self._trailing_text_obj)

    def on_trailing_text_color(self, instance, value):
        self._trailing_text_obj.text_color = value


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


Example().run()
API - kivymd.uix.navigationdrawer.navigationdrawer#
class kivymd.uix.navigationdrawer.navigationdrawer.BaseNavigationDrawerItem#

Implement the base class for the menu list item.

New in version 2.0.0.

selected#

Is the item selected.

selected is a BooleanProperty and defaults to False.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationLayout(*args, **kwargs)#

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

update_pos(instance_navigation_drawer, pos_x: float) None#
add_scrim(instance_manager: kivy.uix.screenmanager.ScreenManager) None#
update_scrim_rectangle(instance_manager: kivy.uix.screenmanager.ScreenManager, size: list) None#
add_widget(widget, index=0, canvas=None)#

Only two layouts are allowed: ScreenManager and MDNavigationDrawer.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerLabel(*args, **kwargs)#

Implements a label class.

For more information, see in the MDLabel class documentation.

New in version 1.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerDivider(**kwargs)#

Implements a divider class.

For more information, see in the BoxLayout class documentation.

New in version 1.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerHeader(*args, **kwargs)#

Implements a header class.

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

New in version 1.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItem(*args, **kwargs)#

Implements an item for the MDNavigationDrawer menu list.

For more information, see in the MDListItem and FocusBehavior and BaseNavigationDrawerItem classes documentation.

New in version 1.0.0.

active_indicator_color#

The active indicator color in (r, g, b, a) or string format.

New in version 2.0.0.

active_indicator_color is a ColorProperty and defaults to None.

inactive_indicator_color#

The inactive indicator color in (r, g, b, a) or string format.

New in version 2.0.0.

inactive_indicator_color is a ColorProperty and defaults to None.

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)
on_release(*args) None#

Fired when the item is released (i.e. the touch/click that pressed the item goes away).

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemLeadingIcon(*args, **kwargs)#

Implements the leading icon for the menu list item.

For more information, see in the MDListItemLeadingIcon and BaseNavigationDrawerItem classes documentation.

New in version 2.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemText(*args, **kwargs)#

Implements the text for the menu list item.

For more information, see in the MDListItemSupportingText and BaseNavigationDrawerItem classes documentation.

New in version 2.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemTrailingText(*args, **kwargs)#

Implements the supporting text for the menu list item.

For more information, see in the MDListItemTrailingSupportingText and BaseNavigationDrawerItem classes documentation.

New in version 2.0.0.

class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerMenu(*args, **kwargs)#

Implements a scrollable list for menu items of the MDNavigationDrawer class.

For more information, see in the MDScrollView class documentation.

New in version 1.0.0.

MDNavigationDrawer:

    MDNavigationDrawerMenu:

        # Your menu items.
        ...
spacing#

Spacing between children, in pixels.

spacing is a NumericProperty and defaults to 0.

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)
update_items_color(item: MDNavigationDrawerItem) None#
class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawer(*args, **kwargs)#

Navigation drawer class.

For more information, see in the MDCard class documentation.

Events:

New in version 2.0.0.

on_open:

Fired when the navigation drawer is opened.

on_close:

Fired when the navigation drawer is closed.

drawer_type#

Type of drawer. Modal type will be on top of screen. Standard type will be at left or right of screen. Also it automatically disables close_on_click and enable_swiping to prevent closing drawer for standard type.

Changed in version 2.0.0: Rename from type to drawer_type.

drawer_type is a OptionProperty and defaults to ‘modal’.

anchor#

Anchoring screen edge for drawer. Set it to ‘right’ for right-to-left languages. Available options are: ‘left’, ‘right’.

anchor is a OptionProperty and defaults to ‘left’.

scrim_color#

Color for scrim in (r, g, b, a) or string format. Alpha channel will be multiplied with _scrim_alpha. Set fourth channel to 0 if you want to disable scrim.

scrim_color is a ColorProperty and defaults to [0, 0, 0, 0.5].

padding#

Padding between layout box and children: [padding_left, padding_top, padding_right, padding_bottom].

Padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].

Changed in version 1.0.0.

MDNavigationDrawer:
    padding: "56dp"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-drawer-padding.png

padding is a VariableListProperty and defaults to ‘[dp(16), dp(16), dp(12), dp(16)]’.

close_on_click#

Close when click on scrim or keyboard escape. It automatically sets to False for “standard” type.

close_on_click is a BooleanProperty and defaults to True.

state#

Indicates if panel closed or opened. Sets after status change. Available options are: ‘close’, ‘open’.

state is a OptionProperty and defaults to ‘close’.

status#

Detailed state. Sets before state. Bind to state instead of status. Available options are: ‘closed’, ‘opening_with_swipe’, ‘opening_with_animation’, ‘opened’, ‘closing_with_swipe’, ‘closing_with_animation’.

status is a OptionProperty and defaults to ‘closed’.

open_progress#

Percent of visible part of side panel. The percent is specified as a floating point number in the range 0-1. 0.0 if panel is closed and 1.0 if panel is opened.

open_progress is a NumericProperty and defaults to 0.0.

enable_swiping#

Allow to open or close navigation drawer with swipe. It automatically sets to False for “standard” type.

enable_swiping is a BooleanProperty and defaults to True.

swipe_distance#

The distance of the swipe with which the movement of navigation drawer begins.

swipe_distance is a NumericProperty and defaults to 10.

swipe_edge_width#

The size of the area in px inside which should start swipe to drag navigation drawer.

swipe_edge_width is a NumericProperty and defaults to 20.

scrim_alpha_transition#

The name of the animation transition type to use for changing scrim_alpha.

scrim_alpha_transition is a StringProperty and defaults to ‘linear’.

opening_transition#

The name of the animation transition type to use when animating to the state ‘open’.

opening_transition is a StringProperty and defaults to ‘out_cubic’.

opening_time#

The time taken for the panel to slide to the state ‘open’.

opening_time is a NumericProperty and defaults to 0.2.

closing_transition#

The name of the animation transition type to use when animating to the state ‘close’.

closing_transition is a StringProperty and defaults to ‘out_sine’.

closing_time#

The time taken for the panel to slide to the state ‘close’.

closing_time is a NumericProperty and defaults to 0.2.

background_color#

The drawer background color in (r, g, b, a) or string format.

New in version 2.0.0.

background_color is a ColorProperty and defaults to None.

theme_elevation_level = 'Custom'#

Drawer elevation level scheme name.

New in version 2.0.0.

Available options are: ‘Primary’, ‘Custom’.

theme_elevation_level is an OptionProperty and defaults to ‘Custom’.

elevation_level = 1#

Drawer elevation level (values from 0 to 5)

New in version 2.2.0.

elevation_level is an BoundedNumericProperty and defaults to 2.

set_properties_widget() None#

Fired on_release/on_press/on_enter/on_leave events.

set_state(new_state='toggle', animation=True) None#

Change state of the side panel. New_state can be one of “toggle”, “open” or “close”.

update_status(*args) None#
get_dist_from_side(x: float) float#
on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_move(touch)#

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)#

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_radius(instance_navigation_drawer, radius_value: list) None#

Fired when the radius value changes.

on_drawer_type(instance_navigation_drawer, drawer_type: str) None#

Fired when the drawer_type value changes.

on_open(*args) None#

Fired when the navigation drawer is opened.

on_close(*args) None#

Fired when the navigation drawer is closed.

ExpansionPanel#

#

Expansion panels contain creation flows and allow lightweight editing of an element.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/expansion-panel.png
Usage#
MDExpansionPanel:

    MDExpansionPanelHeader:

        # Content of header.
        [...]

    MDExpansionPanelContent:

        # Content of panel.
        [...]
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/expansion-panel-anatomy.png
Example#
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import RotateBehavior
from kivymd.uix.expansionpanel import MDExpansionPanel
from kivymd.uix.list import MDListItemTrailingIcon

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

    MDExpansionPanel:
        id: panel
        pos_hint: {"center_x": .5, "center_y": .5}

        MDExpansionPanelHeader:

            MDListItem:
                theme_bg_color: "Custom"
                md_bg_color: self.theme_cls.surfaceContainerLowColor
                ripple_effect: False

                MDListItemSupportingText:
                    text: "Supporting text"

                TrailingPressedIconButton:
                    id: chevron
                    icon: "chevron-right"
                    on_release: app.tap_expansion_chevron(panel, chevron)

        MDExpansionPanelContent:
            orientation: "vertical"
            padding: "12dp", 0, "12dp", 0

            MDLabel:
                text: "Channel information"
                adaptive_height: True
                padding_x: "16dp"
                padding_y: "12dp"

            MDListItem:

                MDListItemLeadingIcon:
                    icon: "email"

                MDListItemHeadlineText:
                    text: "Email"

                MDListItemSupportingText:
                    text: "kivydevelopment@gmail.com"

            MDListItem:

                MDListItemLeadingIcon:
                    icon: "instagram"

                MDListItemHeadlineText:
                    text: "Instagram"

                MDListItemSupportingText:
                    text: "Account"

                MDListItemTertiaryText:
                    text: "www.instagram.com/KivyMD"
'''


class TrailingPressedIconButton(
    ButtonBehavior, RotateBehavior, MDListItemTrailingIcon
):
    ...


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

    def tap_expansion_chevron(
        self, panel: MDExpansionPanel, chevron: TrailingPressedIconButton
    ):
        panel.open() if not panel.is_open else panel.close()
        panel.set_chevron_down(
            chevron
        ) if not panel.is_open else panel.set_chevron_up(chevron)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/expansion-panel-example.gif
Use with ScrollView#
import asynckivy
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.metrics import dp
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import RotateBehavior
from kivymd.uix.expansionpanel import MDExpansionPanel
from kivymd.uix.list import MDListItemTrailingIcon

KV = '''
<ExpansionPanelItem>

    MDExpansionPanelHeader:

        MDListItem:
            theme_bg_color: "Custom"
            md_bg_color: self.theme_cls.surfaceContainerLowColor
            ripple_effect: False

            MDListItemSupportingText:
                text: "Supporting text"

            TrailingPressedIconButton:
                id: chevron
                icon: "chevron-right"
                on_release: app.tap_expansion_chevron(root, chevron)

    MDExpansionPanelContent:
        orientation: "vertical"
        padding: "12dp", 0, "12dp", "12dp"
        md_bg_color: self.theme_cls.surfaceContainerLowestColor

        MDLabel:
            text: "Channel information"
            adaptive_height: True
            padding_x: "16dp"
            padding_y: "12dp"

        MDListItem:
            theme_bg_color: "Custom"
            md_bg_color: self.theme_cls.surfaceContainerLowestColor

            MDListItemLeadingIcon:
                icon: "email"

            MDListItemHeadlineText:
                text: "Email"

            MDListItemSupportingText:
                text: "kivydevelopment@gmail.com"

        MDListItem:
            theme_bg_color: "Custom"
            md_bg_color: self.theme_cls.surfaceContainerLowestColor

            MDListItemLeadingIcon:
                icon: "instagram"

            MDListItemHeadlineText:
                text: "Instagram"

            MDListItemSupportingText:
                text: "Account"

            MDListItemTertiaryText:
                text: "www.instagram.com/KivyMD"


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    ScrollView:
        size_hint_x: .5
        pos_hint: {"center_x": .5, "center_y": .5}

        MDList:
            id: container
'''


class ExpansionPanelItem(MDExpansionPanel):
    ...


class TrailingPressedIconButton(
    ButtonBehavior, RotateBehavior, MDListItemTrailingIcon
):
    ...


class Example(MDApp):
    def on_start(self):
        async def set_panel_list():
            for i in range(12):
                await asynckivy.sleep(0)
                self.root.ids.container.add_widget(ExpansionPanelItem())

        super().on_start()
        asynckivy.start(set_panel_list())

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

    def tap_expansion_chevron(
        self, panel: MDExpansionPanel, chevron: TrailingPressedIconButton
    ):
        Animation(
            padding=[0, dp(12), 0, dp(12)]
            if not panel.is_open
            else [0, 0, 0, 0],
            d=0.2,
        ).start(panel)
        panel.open() if not panel.is_open else panel.close()
        panel.set_chevron_down(
            chevron
        ) if not panel.is_open else panel.set_chevron_up(chevron)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/expansion-panel-example-with-scroll-view.gif
API break#
1.2.0 version#
MDExpansionPanel(
    icon="icon.png",
    content=Content(),  # content of panel
    panel_cls=MDExpansionPanelThreeLine(  # content of header
        text="Text",
        secondary_text="Secondary text",
        tertiary_text="Tertiary text",
    )
)
2.0.0 version#
MDExpansionPanel:

    MDExpansionPanelHeader:

        # Content of header.
        [...]

    MDExpansionPanelContent:

        # Content of panel.
        [...]
API - kivymd.uix.expansionpanel.expansionpanel#
class kivymd.uix.expansionpanel.expansionpanel.MDExpansionPanelContent(*args, **kwargs)#

Implements a container for panel content.

New in version 2.0.0.

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

class kivymd.uix.expansionpanel.expansionpanel.MDExpansionPanelHeader(*args, **kwargs)#

Implements a container for the content of the panel header.

New in version 2.0.0.

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

class kivymd.uix.expansionpanel.expansionpanel.MDExpansionPanel(**kwargs)#

Expansion panel class.

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

Events:
on_open

Fired when a panel is opened.

on_close

Fired when a panel is closed.

opening_transition#

The name of the animation transition type to use when animating to the state ‘open’.

opening_transition is a StringProperty and defaults to ‘out_cubic’.

opening_time#

The time taken for the panel to slide to the state ‘open’.

opening_time is a NumericProperty and defaults to 0.2.

closing_transition#

The name of the animation transition type to use when animating to the state ‘close’.

closing_transition is a StringProperty and defaults to ‘out_sine’.

closing_time#

The time taken for the panel to slide to the state ‘close’.

closing_time is a NumericProperty and defaults to 0.2.

is_open#

The panel is open or closed.

New in version 2.0.0.

is_open is a BooleanProperty and defaults to False.

on_open(*args) None#

Fired when a panel is opened.

on_close(*args) None#

Fired when a panel is closed.

set_chevron_down(instance) None#

Sets the chevron down.

set_chevron_up(instance) None#

Sets the chevron up.

close(*args) None#

Method closes the panel.

Changed in version 2.0.0: Rename from close_panel to close method.

open(*args) None#

Method opens a panel.

Changed in version 2.0.0: Rename from open_panel to open method.

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)

Menu#

#

Menus display a list of choices on temporary surfaces.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-preview.png
  • Menus should be easy to open, close, and interact with

  • Menu content should be suited to user needs

  • Menu items should be easy to scan

Usage#
from kivy.lang import Builder
from kivy.metrics import dp

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

KV = '''
MDScreen:

    MDRaisedButton:
        id: button
        text: "Press me"
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.menu_open()
'''


class Test(MDApp):
    def menu_open(self):
        menu_items = [
            {
                "text": f"Item {i}",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        MDDropdownMenu(
            caller=self.root.ids.button, items=menu_items
        ).open()

    def menu_callback(self, text_item):
        print(text_item)

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


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-usage.gif
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-anatomy.png
You can combine the following parameters:#
  • leading_icon

  • text

  • trailing_icon

  • trailing_text

…to create the necessary types of menu items:

menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
        "trailing_icon": "apple-keyboard-command",
        "trailing_text": "+Shift+X",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-leading-icon-trailing-icon-trailing-text.png
menu_items = [
    {
        "text": "Strikethrough",
        "trailing_icon": "apple-keyboard-command",
        "trailing_text": "+Shift+X",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-trailing-icon-trailing-text.png
menu_items = [
    {
        "text": "Strikethrough",
        "trailing_icon": "apple-keyboard-command",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-trailing-icon.png
menu_items = [
    {
        "text": "Strikethrough",
        "trailing_text": "Shift+X",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-trailing-text.png
menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
        "trailing_icon": "apple-keyboard-command",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-leading-icon-trailing-icon.png
menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-leading-icon.png
menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
        "trailing_text": "Shift+X",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-leading-icon-trailing-text.png
menu_items = [
    {
        "text": "Strikethrough",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-text.png
You can use the following parameters to customize the menu items:#
  • text_color

  • leading_icon_color

  • trailing_icon_color

  • trailing_text_color

menu_items = [
    {
        "text": "Strikethrough",
        "leading_icon": "check",
        "trailing_icon": "apple-keyboard-command",
        "trailing_text": "+Shift+X",
        "leading_icon_color": "orange",
        "trailing_icon_color": "green",
        "trailing_text_color": "red",
    }
]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-item-customize.png
Position#
Bottom position#

See also

position

from kivy.lang import Builder
from kivy.metrics import dp

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

KV = '''
MDScreen:

    MDTextField:
        id: field
        pos_hint: {'center_x': .5, 'center_y': .6}
        size_hint_x: None
        width: "200dp"
        hint_text: "Password"
        on_focus: if self.focus: app.menu.open()
'''


class Test(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)
        menu_items = [
            {
                "text": f"Item {i}",
                "on_release": lambda x=f"Item {i}": self.set_item(x),
            } for i in range(5)]
        self.menu = MDDropdownMenu(
            caller=self.screen.ids.field,
            items=menu_items,
            position="bottom",
        )

    def set_item(self, text_item):
        self.screen.ids.field.text = text_item
        self.menu.dismiss()

    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Dark"
        return self.screen


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-position.png
Center position#
from kivy.lang import Builder

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

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

    MDDropDownItem:
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.open_drop_item_menu(self)

        MDDropDownItemText:
            id: drop_text
            text: "Item"
'''


class Example(MDApp, CommonApp):
    drop_item_menu: MDDropdownMenu = None

    def open_drop_item_menu(self, item):
        menu_items = [
            {
                "text": f"{i}",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        if not self.drop_item_menu:
            self.drop_item_menu = MDDropdownMenu(
                caller=item, items=menu_items, position="center"
            )
            self.drop_item_menu.open()

    def menu_callback(self, text_item):
        self.root.ids.drop_text.text = text_item
        self.drop_item_menu.dismiss()

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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-position-center.gif
API break#
1.1.1 version#
from kivy.lang import Builder
from kivy.metrics import dp
from kivy.properties import StringProperty

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.list import IRightBodyTouch, OneLineAvatarIconListItem
from kivymd.uix.menu import MDDropdownMenu

KV = '''
<RightContentCls>
    disabled: True
    adaptive_size: True
    pos_hint: {"center_y": .5}

    MDIconButton:
        icon: root.icon
        icon_size: "16sp"
        md_bg_color_disabled: 0, 0, 0, 0

    MDLabel:
        text: root.text
        font_style: "Caption"
        adaptive_size: True
        pos_hint: {"center_y": .5}


<Item>

    IconLeftWidget:
        icon: root.left_icon

    RightContentCls:
        id: container
        icon: root.right_icon
        text: root.right_text


MDScreen:

    MDRaisedButton:
        id: button
        text: "PRESS ME"
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.menu.open()
'''


class RightContentCls(IRightBodyTouch, MDBoxLayout):
    icon = StringProperty()
    text = StringProperty()


class Item(OneLineAvatarIconListItem):
    left_icon = StringProperty()
    right_icon = StringProperty()
    right_text = StringProperty()


class Test(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)
        menu_items = [
            {
                "text": f"Item {i}",
                "right_text": "+Shift+X",
                "right_icon": "apple-keyboard-command",
                "left_icon": "web",
                "viewclass": "Item",
                "height": dp(54),
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        self.menu = MDDropdownMenu(
            caller=self.screen.ids.button,
            items=menu_items,
            bg_color="#bdc6b0",
            width_mult=4,
        )

    def menu_callback(self, text_item):
        print(text_item)

    def build(self):
        return self.screen


Test().run()
1.2.0 version#
from kivy.lang import Builder
from kivy.metrics import dp

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

KV = '''
MDScreen:

    MDRaisedButton:
        id: button
        text: "PRESS ME"
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.menu.open()
'''


class Test(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)
        menu_items = [
            {
                "text": f"Item {i}",
                "leading_icon": "web",
                "trailing_icon": "apple-keyboard-command",
                "trailing_text": "+Shift+X",
                "trailing_icon_color": "grey",
                "trailing_text_color": "grey",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        self.menu = MDDropdownMenu(
            md_bg_color="#bdc6b0",
            caller=self.screen.ids.button,
            items=menu_items,
        )

    def menu_callback(self, text_item):
        print(text_item)

    def build(self):
        return self.screen


Test().run()
API - kivymd.uix.menu.menu#
class kivymd.uix.menu.menu.BaseDropdownItem(**kwargs)#

Base class for menu items.

New in version 1.2.0.

For more information, see in the RectangularRippleBehavior and MDBoxLayout classes.

text#

The text of the menu item.

text is a StringProperty and defaults to ‘’.

leading_icon#

The leading icon of the menu item.

leading_icon is a StringProperty and defaults to ‘’.

trailing_icon#

The trailing icon of the menu item.

trailing_icon is a StringProperty and defaults to ‘’.

trailing_text#

The trailing text of the menu item.

trailing_text is a StringProperty and defaults to ‘’.

text_color#

The color of the text in (r, g, b, a) or string format for the text of the menu item.

text_color is a ColorProperty and defaults to None.

leading_icon_color#

The color of the text in (r, g, b, a) or string format for the leading icon of the menu item.

leading_icon_color is a ColorProperty and defaults to None.

trailing_icon_color#

The color of the text in (r, g, b, a) or string format for the trailing icon of the menu item.

leading_icon_color is a ColorProperty and defaults to None.

trailing_text_color#

The color of the text in (r, g, b, a) or string format for the trailing text of the menu item.

leading_icon_color is a ColorProperty and defaults to None.

divider#

Divider mode. Available options are: ‘Full’, None and default to ‘Full’.

divider is a OptionProperty and defaults to ‘Full’.

divider_color#

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

divider_color is a ColorProperty and defaults to None.

class kivymd.uix.menu.menu.MDDropdownTextItem(**kwargs)#

Implements a menu item with text without leading and trailing icons.

New in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownLeadingIconItem(**kwargs)#

Implements a menu item with text, leading icon and without trailing icon.

New in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownTrailingIconItem(**kwargs)#

Implements a menu item with text, without leading icon and with trailing icon.

New in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownTrailingIconTextItem(**kwargs)#

Implements a menu item with text, without leading icon, with trailing icon and with trailing text.

New in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownTrailingTextItem(**kwargs)#

Implements a menu item with text, without leading icon, without trailing icon and with trailing text.

New in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownLeadingIconTrailingTextItem(**kwargs)#

Implements a menu item with text, leading icon and with trailing text.

New in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownLeadingTrailingIconTextItem(**kwargs)#

Implements a menu item with text, with leading icon, with trailing icon and with trailing text.

New in version 1.2.0.

For more information, see in the BaseDropdownItem class.

class kivymd.uix.menu.menu.MDDropdownMenu(**kwargs)#

Dropdown menu class.

For more information, see in the MotionDropDownMenuBehavior and StencilBehavior and MDCard classes documentation.

Events:
on_release

The method that will be called when you click menu items.

header_cls#

An instance of the class (Kivy or KivyMD widget) that will be added to the menu header.

New in version 0.104.2.

See Header for more information.

header_cls is a ObjectProperty and defaults to None.

items#

List of dictionaries with properties for menu items.

items is a ListProperty and defaults to [].

width_mult#

This number multiplied by the standard increment (‘56dp’ on mobile, ‘64dp’ on desktop), determines the width of the menu items.

If the resulting number were to be too big for the application Window, the multiplier will be adjusted for the biggest possible one.

Deprecated since version 1.2.0: Use width instead.

self.menu = MDDropdownMenu(
    width=dp(240),
    ...,
)

width_mult is a NumericProperty and defaults to 1.

min_height#
max_height#

The menu will grow no bigger than this number. Set to 0 for no limit.

max_height is a NumericProperty and defaults to 0.

border_margin#

Margin between Window border and menu.

self.menu = MDDropdownMenu(
    border_margin=dp(24),
    ...,
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-border-margin-24.png

border_margin is a NumericProperty and defaults to 4dp.

ver_growth#

Where the menu will grow vertically to when opening. Set to None to let the widget pick for you. Available options are: ‘up’, ‘down’.

self.menu = MDDropdownMenu(
    ver_growth="up",
    ...,
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-ver-growth-up.png
self.menu = MDDropdownMenu(
    ver_growth="down",
    ...,
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-ver-growth-down.png

ver_growth is a OptionProperty and defaults to None.

hor_growth#

Where the menu will grow horizontally to when opening. Set to None to let the widget pick for you. Available options are: ‘left’, ‘right’.

self.menu = MDDropdownMenu(
    hor_growth="left",
    ...,
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-hor-growth-left.png
self.menu = MDDropdownMenu(
    hor_growth="right",
    ...,
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/menu-hor-growth-right.png

hor_growth is a OptionProperty and defaults to None.

background_color#

Color in (r, g, b, a) or string format of the background of the menu.

Deprecated since version 1.2.0: Use md_bg_color instead.

background_color is a ColorProperty and defaults to None.

caller#

The widget object that calls the menu window.

caller is a ObjectProperty and defaults to None.

position#

Menu window position relative to parent element. Available options are: ‘auto’, ‘top’, ‘center’, ‘bottom’.

See Position for more information.

position is a OptionProperty and defaults to ‘auto’.

radius#

Menu radius.

radius is a VariableListProperty and defaults to ‘[dp(7)]’.

adjust_width() None#

Adjust the width of the menu if the width of the menu goes beyond the boundaries of the parent window from starting point.

check_ver_growth() None#

Checks whether the height of the lower/upper borders of the menu exceeds the limits borders of the parent window.

check_hor_growth() None#

Checks whether the width of the left/right menu borders exceeds the boundaries of the parent window.

get_target_pos() [float, float]#
set_target_height() None#

Set the target height of the menu depending on the size of each item.

set_menu_properties(*args) None#

Sets the size and position for the menu window.

set_menu_pos(*args) None#
adjust_position() str#

Return value ‘auto’ for the menu position if the menu position is out of screen.

open() None#

Animate the opening of a menu window.

on_items(instance, value: list) None#

The method sets the class that will be used to create the menu item.

on_header_cls(instance_dropdown_menu, instance_user_menu_header) None#

Called when a value is set to the header_cls parameter.

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_move(touch)#

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)#

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

dismiss(*args) None#

Closes the menu.

FileManager#

#

A simple manager for selecting directories and files.

Usage#
path = os.path.expanduser("~")  # path to the directory that will be opened in the file manager
file_manager = MDFileManager(
    exit_manager=self.exit_manager,  # function called when the user reaches directory tree root
    select_path=self.select_path,  # function called when selecting a file/directory
)
file_manager.show(path)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager.png

Warning

Be careful! To use the ‘/’ path on Android devices, you need special permissions. Therefore, you are likely to get an error.

Or with preview mode:

file_manager = MDFileManager(
    exit_manager=self.exit_manager,
    select_path=self.select_path,
    preview=True,
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-preview.png

Warning

The preview mode is intended only for viewing images and will not display other types of files.

Example#
import os

from kivy.core.window import Window
from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.filemanager import MDFileManager
from kivymd.uix.snackbar import MDSnackbar, MDSnackbarText

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

    MDButton:
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.file_manager_open()

        MDButtonText:
            text: "Open manager"
'''


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        Window.bind(on_keyboard=self.events)
        self.manager_open = False
        self.file_manager = MDFileManager(
            exit_manager=self.exit_manager, select_path=self.select_path
        )

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

    def file_manager_open(self):
        self.file_manager.show(
            os.path.expanduser("~"))  # output manager to the screen
        self.manager_open = True

    def select_path(self, path: str):
        '''
        It will be called when you click on the file name
        or the catalog selection button.

        :param path: path to the selected directory or file;
        '''

        self.exit_manager()
        MDSnackbar(
            MDSnackbarText(
                text=path,
            ),
            y=dp(24),
            pos_hint={"center_x": 0.5},
            size_hint_x=0.8,
        ).open()

    def exit_manager(self, *args):
        '''Called when the user reaches the root of the directory tree.'''

        self.manager_open = False
        self.file_manager.close()

    def events(self, instance, keyboard, keycode, text, modifiers):
        '''Called when buttons are pressed on the mobile device.'''

        if keyboard in (1001, 27):
            if self.manager_open:
                self.file_manager.back()
        return True


Example().run()

New in version 1.0.0.

Added a feature that allows you to show the available disks first, then the files contained in them. Works correctly on: Windows, Linux, OSX, Android. Not tested on iOS.

def file_manager_open(self):
    self.file_manager.show_disks()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-show-disks.png
API - kivymd.uix.filemanager.filemanager#
class kivymd.uix.filemanager.filemanager.MDFileManager(*args, **kwargs)#

Implements a modal dialog with a file manager.

For more information, see in the ThemableBehavior and RelativeLayout classes documentation.

Events:
on_pre_open:

Called before the MDFileManager is opened.

on_open:

Called when the MDFileManager is opened.

on_pre_dismiss:

Called before the MDFileManager is closed.

on_dismiss:

Called when the MDFileManager is closed.

icon#

Icon that will be used on the directory selection button.

Deprecated since version 1.1.0: Use icon_selection_button instead.

icon is an StringProperty and defaults to check.

icon_selection_button#

Icon that will be used on the directory selection button.

New in version 1.1.0.

MDFileManager(
    ...
    icon_selection_button="pencil",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-icon-selection-button.png

icon_selection_button is an StringProperty and defaults to check.

background_color_selection_button#

Background color in (r, g, b, a) or string format of the current directory/path selection button.

New in version 1.1.0.

MDFileManager(
    ...
    background_color_selection_button="brown",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-background-color-selection-button.png

background_color_selection_button is an ColorProperty and defaults to None.

background_color_toolbar#

Background color in (r, g, b, a) or string format of the file manager toolbar.

New in version 1.1.0.

MDFileManager(
    ...
    background_color_toolbar="brown",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-background-color-toolbar.png

background_color_toolbar is an ColorProperty and defaults to None.

icon_folder#

Icon that will be used for folder icons when using preview = True.

MDFileManager(
    ...
    preview=True,
    icon_folder="path/to/icon.png",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-icon-folder.png

icon is an StringProperty and defaults to check.

icon_color#

Color in (r, g, b, a) or string format of the folder icon when the preview property is set to False.

New in version 1.1.0.

MDFileManager(
    ...
    preview=False,
    icon_color="brown",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-icon-color.png

icon_color is an ColorProperty and defaults to None.

exit_manager#

Function called when the user reaches directory tree root.

exit_manager is an ObjectProperty and defaults to lambda x: None.

select_path#

Function, called when selecting a file/directory.

select_path is an ObjectProperty and defaults to lambda x: None.

ext#

List of file extensions to be displayed in the manager. For example, [‘.py’, ‘.kv’] - will filter out all files, except python scripts and Kv Language.

ext is an ListProperty and defaults to [].

search#

It can take the values ‘all’ ‘dirs’ ‘files’ - display only directories or only files or both them. By default, it displays folders, and files. Available options are: ‘all’, ‘dirs’, ‘files’.

search is an OptionProperty and defaults to all.

current_path#

Current directory.

current_path is an StringProperty and defaults to os.path.expanduser(“~”).

use_access#

Show access to files and directories.

use_access is an BooleanProperty and defaults to True.

preview#

Shows only image previews.

preview is an BooleanProperty and defaults to False.

show_hidden_files#

Shows hidden files.

show_hidden_files is an BooleanProperty and defaults to False.

sort_by#

It can take the values ‘nothing’ ‘name’ ‘date’ ‘size’ ‘type’ - sorts files by option. By default, sort by name. Available options are: ‘nothing’, ‘name’, ‘date’, ‘size’, ‘type’.

sort_by is an OptionProperty and defaults to name.

sort_by_desc#

Sort by descending.

sort_by_desc is an BooleanProperty and defaults to False.

selector#

It can take the values ‘any’ ‘file’ ‘folder’ ‘multi’ By default, any. Available options are: ‘any’, ‘file’, ‘folder’, ‘multi’.

selector is an OptionProperty and defaults to any.

selection#

Contains the list of files that are currently selected.

selection is a read-only ListProperty and defaults to [].

selection_button#

The instance of the directory/path selection button.

New in version 1.1.0.

selection_button is a read-only ObjectProperty and defaults to None.

show_disks() None#
show(path: str) None#

Forms the body of a directory tree.

Parameters:

path – The path to the directory that will be opened in the file manager.

get_access_string(path: str) str#
get_content() Tuple[List[str], List[str]] | Tuple[None, None]#

Returns a list of the type [[Folder List], [file list]].

close() None#

Closes the file manager window.

select_dir_or_file(path: str, widget: MDFileManagerItemPreview | MDFileManagerItem) None#

Called by tap on the name of the directory or file.

back() None#

Returning to the branch down in the directory tree.

select_directory_on_press_button(*args) None#

Called when a click on a floating button.

on_icon(instance_file_manager, icon_name: str) None#

Called when the icon property is changed.

on_background_color_toolbar(instance_file_manager, color: str | list) None#

Called when the background_color_toolbar property is changed.

on_pre_open(*args) None#

Default pre-open event handler.

New in version 1.1.0.

on_open(*args) None#

Default open event handler.

New in version 1.1.0.

on_pre_dismiss(*args) None#

Default pre-dismiss event handler.

New in version 1.1.0.

on_dismiss(*args) None#

Default dismiss event handler.

New in version 1.1.0.

List#

#

Lists are continuous, vertical indexes of text or images.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/lists.png
  • Use lists to help users find a specific item and act on it;

  • Order list items in logical ways (like alphabetical or numerical);

  • Three sizes: one-line, two-line, and three-line;

  • Keep items short and easy to scan;

  • Show icons, text, and actions in a consistent format;

Usage#
MDListItem:

    MDListItemLeadingIcon:  # MDListItemLeadingAvatar

    MDListItemHeadlineText:

    MDListItemSupportingText:

    MDListItemTertiaryText:

    MDListItemTrailingIcon:  # MDListItemTrailingCheckbox
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/lists-anatomy.png
Example:#
One line list item#
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDListItem:
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint_x: .8

        MDListItemHeadlineText:
            text: "Headline"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-list.gif
Two line list item#
MDListItem:

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-list.png
Three line list item#
MDListItem:

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"

    MDListItemTertiaryText:
        text: "Tertiary text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-tertiary-list.png
List item with leading icon#
MDListItem:

    MDListItemLeadingIcon:
        icon: "account"

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"

    MDListItemTertiaryText:
        text: "Tertiary text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-tertiary-leading-icon-list.png
List item with trailing icon#
MDListItem:

    MDListItemLeadingIcon:
        icon: "account"

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"

    MDListItemTertiaryText:
        text: "Tertiary text"

    MDListItemTrailingIcon:
        icon: "trash-can-outline"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-tertiary-leading-trailing-icon-list.png
List item with trailing check#
MDListItem:

    MDListItemLeadingIcon:
        icon: "account"

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"

    MDListItemTertiaryText:
        text: "Tertiary text"

    MDListItemTrailingCheckbox:
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-tertiary-leading-trailing-check-list.png
API - kivymd.uix.list.list#
class kivymd.uix.list.list.MDList(*args, **kwargs)#

ListItem container. Best used in conjunction with a kivy.uix.ScrollView.

When adding (or removing) a widget, it will resize itself to fit its children, plus top and bottom paddings as described by the MD spec.

For more information, see in the MDGridLayout class documentation.

class kivymd.uix.list.list.BaseListItem(*args, **kwargs)#

Base class for list items.

For more information, see in the DeclarativeBehavior and BackgroundColorBehavior and RectangularRippleBehavior and ButtonBehavior and ThemableBehavior and StateLayerBehavior classes documentation.

divider#

Should I use divider for a list item.

divider is an BooleanProperty and defaults to False.

divider_color#

The divider color in (r, g, b, a) or string format.

divider_color is a ColorProperty and defaults to None.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.list.list.BaseListItemText(*args, **kwargs)#

Base class for text labels of a list item.

For more information, see in the MDLabel class documentation.

class kivymd.uix.list.list.BaseListItemIcon(*args, **kwargs)#

Base class for leading/trailing icon of list item.

For more information, see in the MDIcon class documentation.

icon_color#

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

icon_color is a ColorProperty and defaults to None.

icon_color_disabled#

The icon color in (r, g, b, a) or string format of the list item when the list item is disabled.

icon_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.list.list.MDListItemHeadlineText(*args, **kwargs)#

Implements a class for headline text of list item.

For more information, see in the BaseListItemText class documentation.

class kivymd.uix.list.list.MDListItemSupportingText(*args, **kwargs)#

Implements a class for secondary text of list item.

For more information, see in the BaseListItemText class documentation.

class kivymd.uix.list.list.MDListItemTertiaryText(*args, **kwargs)#

Implements a class for tertiary text of list item.

For more information, see in the BaseListItemText class documentation.

class kivymd.uix.list.list.MDListItemTrailingSupportingText(*args, **kwargs)#

Implements a class for trailing text of list item.

For more information, see in the BaseListItemText class documentation.

class kivymd.uix.list.list.MDListItemLeadingIcon(*args, **kwargs)#

Implements a class for leading icon class.

For more information, see in the BaseListItemIcon class documentation.

class kivymd.uix.list.list.MDListItemLeadingAvatar(**kwargs)#

Implements a class for leading avatar class.

For more information, see in the ThemableBehavior and CircularRippleBehavior and ButtonBehavior and FitImage classes documentation.

class kivymd.uix.list.list.MDListItemTrailingIcon(*args, **kwargs)#

Implements a class for trailing icon class.

For more information, see in the BaseListItemIcon class documentation.

class kivymd.uix.list.list.MDListItemTrailingCheckbox(**kwargs)#

Implements a class for trailing checkbox class.

For more information, see in the MDCheckbox class documentation.

class kivymd.uix.list.list.MDListItem(*args, **kwargs)#

Implements a list item.

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

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)

Card#

#

Cards contain content and actions about a single subject.

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

KivyMD provides the following card classes for use:

Note

MDCard inherited from BoxLayout. You can use all parameters and attributes of the BoxLayout class in the MDCard class.

MDCard#

There are three types of cards: elevated, filled, and outlined:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/available-cards.png
  1. Elevated card

  2. Filled card

  3. Outlined card

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

from kivymd.app import MDApp
from kivymd.uix.card import MDCard

KV = '''
<MyCard>
    padding: "4dp"
    size_hint: None, None
    size: "240dp", "100dp"

    MDRelativeLayout:

        MDIconButton:
            icon: "dots-vertical"
            pos_hint: {"top": 1, "right": 1}

        MDLabel:
            text: root.text
            adaptive_size: True
            color: "grey"
            pos: "12dp", "12dp"
            bold: True


MDScreen:
    theme_bg_color: "Custom"
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        id: box
        adaptive_size: True
        spacing: "12dp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class MyCard(MDCard):
    '''Implements a material card.'''

    text = StringProperty()


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

    def on_start(self):
        super().on_start()
        for style in ("elevated", "filled", "outlined"):
            self.root.ids.box.add_widget(
                MyCard(style=style, text=style.capitalize())
            )


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-usage.png
Elevated#
MDCard
    style: "elevated"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-elevated.png
Filled#
MDCard
    style: "filled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-filled.png
Outlined#
MDCard
    style: "outlined"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-outlined.png
Customization of card#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    theme_bg_color: "Custom"
    md_bg_color: self.theme_cls.backgroundColor

    MDCard:
        style: "elevated"
        pos_hint: {"center_x": .5, "center_y": .5}
        padding: "4dp"
        size_hint: None, None
        size: "240dp", "100dp"
        # Sets custom properties.
        theme_shadow_color: "Custom"
        shadow_color: "green"
        theme_bg_color: "Custom"
        md_bg_color: "white"
        md_bg_color_disabled: "grey"
        theme_shadow_offset: "Custom"
        shadow_offset: (1, -2)
        theme_shadow_softness: "Custom"
        shadow_softness: 1
        theme_elevation_level: "Custom"
        elevation_level: 2

        MDRelativeLayout:

            MDIconButton:
                icon: "dots-vertical"
                pos_hint: {"top": 1, "right": 1}

            MDLabel:
                text: "Elevated"
                adaptive_size: True
                color: "grey"
                pos: "12dp", "12dp"
                bold: True
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-customization.png
MDCardSwipe#

To create a card with swipe-to-delete behavior, you must create a new class that inherits from the MDCardSwipe class:

<SwipeToDeleteItem>
    size_hint_y: None
    height: content.height

    MDCardSwipeLayerBox:

    MDCardSwipeFrontBox:

        OneLineListItem:
            id: content
            text: root.text
            _no_ripple_effect: True
class SwipeToDeleteItem(MDCardSwipe):
    text = StringProperty()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sceleton-mdcard-swiper.png
Example#
from kivy.lang import Builder
from kivy.properties import StringProperty

from kivymd.app import MDApp
from kivymd.uix.card import MDCardSwipe

KV = '''
<SwipeToDeleteItem>:
    size_hint_y: None
    height: content.height

    MDCardSwipeLayerBox:
        padding: "8dp"

        MDIconButton:
            icon: "trash-can"
            pos_hint: {"center_y": .5}
            on_release: app.remove_item(root)

    MDCardSwipeFrontBox:

        OneLineListItem:
            id: content
            text: root.text
            _no_ripple_effect: True


MDScreen:

    MDScrollView:

        MDList:
            id: md_list
            padding: 0
'''


class SwipeToDeleteItem(MDCardSwipe):
    text = StringProperty()


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        self.screen = Builder.load_string(KV)

    def build(self):
        return self.screen

    def remove_item(self, instance):
        self.screen.ids.md_list.remove_widget(instance)

    def on_start(self):
        super().on_start()
        for i in range(20):
            self.screen.ids.md_list.add_widget(
                SwipeToDeleteItem(text=f"One-line item {i}")
            )


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/list-mdcard-swipe.gif
Binding a swipe to one of the sides of the screen#
<SwipeToDeleteItem>
    # By default, the parameter is "left"
    anchor: "right"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mdcard-swipe-anchor-right.gif

Note

You cannot use the left and right swipe at the same time.

Swipe behavior#
<SwipeToDeleteItem>
    # By default, the parameter is "hand"
    type_swipe: "hand"  # "auto"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hand-mdcard-swipe.gif
Removing an item using the type_swipe = "auto" parameter#

The map provides the MDCardSwipe.on_swipe_complete event. You can use this event to remove items from a list:

<SwipeToDeleteItem>:
    on_swipe_complete: app.on_swipe_complete(root)
def on_swipe_complete(self, instance):
    self.root.ids.md_list.remove_widget(instance)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/auto-mdcard-swipe.gif
Add content to the bottom layer of the card#

To add content to the bottom layer of the card, use the MDCardSwipeLayerBox class.

<SwipeToDeleteItem>:

    MDCardSwipeLayerBox:
        padding: "8dp"

        MDIconButton:
            icon: "trash-can"
            pos_hint: {"center_y": .5}
            on_release: app.remove_item(root)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mdcard-swipe-content.png
API - kivymd.uix.card.card#
class kivymd.uix.card.card.MDCard(*args, **kwargs)#

Card class.

For more information, see in the DeclarativeBehavior and MDAdaptiveWidget and ThemableBehavior and BackgroundColorBehavior and CommonElevationBehavior and RectangularRippleBehavior and StateLayerBehavior and ButtonBehavior and BoxLayout and classes documentation.

ripple_behavior#

Use ripple effect for card.

ripple_behavior is a BooleanProperty and defaults to False.

radius#

Card radius by default.

New in version 1.0.0.

radius is an VariableListProperty and defaults to [dp(16), dp(16), dp(16), dp(16)].

style#

Card type.

New in version 1.0.0.

Available options are: ‘filled’, ‘elevated’, ‘outlined’.

style is an OptionProperty and defaults to None.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

on_press(*args) None#

Fired when the button is pressed.

on_release(*args) None#

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

on_ripple_behavior(interval: int | float, value: bool) None#

Fired when the ripple_behavior value changes.

set_properties_widget() None#

Fired on_release/on_press/on_enter/on_leave events.

class kivymd.uix.card.card.MDCardSwipe(*args, **kwargs)#

Card swipe class.

For more information, see in the MDRelativeLayout class documentation.

Events:
on_swipe_complete

Fired when a swipe of card is completed.

open_progress#

Percent of visible part of side panel. The percent is specified as a floating point number in the range 0-1. 0.0 if panel is closed and 1.0 if panel is opened.

open_progress is a NumericProperty and defaults to 0.0.

opening_transition#

The name of the animation transition type to use when animating to the state ‘opened’.

opening_transition is a StringProperty and defaults to ‘out_cubic’.

closing_transition#

The name of the animation transition type to use when animating to the state ‘closed’.

closing_transition is a StringProperty and defaults to ‘out_sine’.

closing_interval#

Interval for closing the front layer.

New in version 1.1.0.

closing_interval is a NumericProperty and defaults to 0.

anchor#

Anchoring screen edge for card. Available options are: ‘left’, ‘right’.

anchor is a OptionProperty and defaults to left.

swipe_distance#

The distance of the swipe with which the movement of navigation drawer begins.

swipe_distance is a NumericProperty and defaults to 50.

opening_time#

The time taken for the card to slide to the state ‘open’.

opening_time is a NumericProperty and defaults to 0.2.

state#

Detailed state. Sets before state. Bind to state instead of status. Available options are: ‘closed’, ‘opened’.

status is a OptionProperty and defaults to ‘closed’.

max_swipe_x#

If, after the events of on_touch_up card position exceeds this value - will automatically execute the method open_card, and if not - will automatically be close_card method.

max_swipe_x is a NumericProperty and defaults to 0.3.

max_opened_x#

The value of the position the card shifts to when type_swipe s set to ‘hand’.

max_opened_x is a NumericProperty and defaults to 100dp.

type_swipe#

Type of card opening when swipe. Shift the card to the edge or to a set position max_opened_x. Available options are: ‘auto’, ‘hand’.

type_swipe is a OptionProperty and defaults to auto.

on_swipe_complete(*args)#

Fired when a swipe of card is completed.

on_anchor(instance_swipe_to_delete_item, anchor_value: str) None#

Fired when the value of anchor changes.

on_open_progress(instance_swipe_to_delete_item, progress_value: float) None#

Fired when the value of open_progress changes.

on_touch_move(touch)#

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)#

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

open_card() None#

Animates the opening of the card.

close_card(*args) None#

Animates the closing of the card.

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)
class kivymd.uix.card.card.MDCardSwipeFrontBox(*args, **kwargs)#

Card swipe front box.

For more information, see in the MDCard class documentation.

class kivymd.uix.card.card.MDCardSwipeLayerBox(*args, **kwargs)#

Card swipe back box.

For more information, see in the MDBoxLayout class documentation.

SegmentedButton#

#

New in version 1.2.0.

Segmented buttons help people select options, switch views, or sort elements.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-preview.png
  • Segmented buttons can contain icons, label text, or both

  • Two types: single-select and multi-select

  • Use for simple choices between two to five items (for more items or complex choices, use chips)

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-types.png
  1. Single-select segmented button

  2. Multi-select segmented button

Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-anatomy.png
Icons#

Icons may be used as labels by themselves or alongside text. If an icon is used without label text, it must clearly communicate the option it represents.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-icons.png
Use with text and icon#
MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-python"

        MDSegmentButtonLabel:
            text: "Python"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-javascript"

        MDSegmentButtonLabel:
            text: "Java-Script"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-swift"

        MDSegmentButtonLabel:
            text: "Swift"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-use-with-text-and-icon.gif
Use without text with an icon#
MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-python"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-javascript"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-swift"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-use-without-text-with-an-icon.gif
Use only text#
MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Python"

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Java-Script"

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Swift"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-use-only-text.gif
Multiselect#

For multiple marking of elements, use the kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButton.multiselect parameter:

MDSegmentedButton:
    multiselect: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-multiselect-true.gif
Type#

Density can be used in denser UIs where space is limited. Density is only applied to the height. Each step down in density removes 4dp from the height.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-type.png
from kivy.lang import Builder

from kivymd.uix.label import MDLabel
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.segmentedbutton import (
    MDSegmentedButton,
    MDSegmentedButtonItem,
    MDSegmentButtonLabel,
)
from kivymd.app import MDApp

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

    MDBoxLayout:
        id: box
        orientation: "vertical"
        size_hint_x: .7
        adaptive_height: True
        spacing: "24dp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Example(MDApp):
    def on_start(self):
        super().on_start()
        for segment_type in ["large", "normal", "medium", "small"]:
            self.root.ids.box.add_widget(
                MDBoxLayout(
                    MDLabel(
                        text=f"Type '{segment_type}'",
                        adaptive_height=True,
                        bold=True,
                        pos_hint={"center_y": 0.5},
                        halign="center",
                    ),
                    MDSegmentedButton(
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Songs",
                            ),
                        ),
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Albums",
                            ),
                        ),
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Podcasts",
                            ),
                        ),
                        type=segment_type,
                    ),
                    orientation="vertical",
                    spacing="12dp",
                    adaptive_height=True,
                )
            )

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


Example().run()
A practical example#
import os

from faker import Faker

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

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

import asynckivy

KV = '''
<UserCard>
    adaptive_height: True
    radius: 16

    MDListItem:
        radius: 16
        theme_bg_color: "Custom"
        md_bg_color: self.theme_cls.secondaryContainerColor

        MDListItemLeadingAvatar:
            source: root.album

        MDListItemHeadlineText:
            text: root.name

        MDListItemSupportingText:
            text: root.path_to_file


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        orientation: "vertical"
        padding: "12dp"
        spacing: "12dp"

        MDLabel:
            adaptive_height: True
            text: "Your downloads"
            theme_font_style: "Custom"
            font_style: "Display"
            role: "small"

        MDSegmentedButton:
            size_hint_x: 1

            MDSegmentedButtonItem:
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Songs"
                    active: True

            MDSegmentedButtonItem:
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Albums"

            MDSegmentedButtonItem:
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Podcasts"

        RecycleView:
            id: card_list
            viewclass: "UserCard"
            bar_width: 0

            RecycleBoxLayout:
                orientation: 'vertical'
                spacing: "16dp"
                padding: "16dp"
                default_size: None, dp(72)
                default_size_hint: 1, None
                size_hint_y: None
                height: self.minimum_height
'''


class UserCard(MDBoxLayout):
    name = StringProperty()
    path_to_file = StringProperty()
    album = StringProperty()


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

    def generate_card(self):
        async def generate_card():
            for i in range(10):
                await asynckivy.sleep(0)
                self.root.ids.card_list.data.append(
                    {
                        "name": fake.name(),
                        "path_to_file": f"{os.path.splitext(fake.file_path())[0]}.mp3",
                        "album": fake.image_url(),
                    }
                )

        fake = Faker()
        self.root.ids.card_list.data = []
        Clock.schedule_once(lambda x: asynckivy.start(generate_card()))


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-practical-example.gif
API break#
1.2.0 version#
MDSegmentedButton:
    on_marked: func(*args)

    MDSegmentedButtonItem:
        icon: ...
        text: ...
2.0.0 version#
MDSegmentedButton:

    MDSegmentedButtonItem:
        on_active: func(*args)

        MDSegmentButtonIcon:
            icon: ...

        MDSegmentButtonLabel:
            text: ...
API - kivymd.uix.segmentedbutton.segmentedbutton#
class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButtonItem(*args, **kwargs)#

Segment button item.

For more information see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and RectangularRippleBehavior and ButtonBehavior and StateLayerBehavior and RelativeLayout and class documentation.

selected_color#

Color of the marked segment.

New in version 2.0.0.

selected_color is a ColorProperty and defaults to None.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

active#

Background color of an disabled segment.

active is an BooleanProperty and defaults to False.

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)
on_line_color(instance, value) None#

Fired when the values of line_color change.

on_active(instance, value) None#

Fired when the active value changes. Animates the marker icon for the element.

on_disabled(instance, value) None#

Fired when the disabled value changes.

class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButton(*args, **kwargs)#

Segment button panel.

For more information, see in the MDBoxLayout class documentation.

multiselect#

Do I allow multiple segment selection.

multiselect is an BooleanProperty and defaults to False.

hiding_icon_transition#

Name of the transition hiding the current icon.

hiding_icon_transition is a StringProperty and defaults to ‘linear’.

hiding_icon_duration#

Duration of hiding the current icon.

hiding_icon_duration is a NumericProperty and defaults to 1.

opening_icon_transition#

The name of the transition that opens a new icon of the “marked” type.

opening_icon_transition is a StringProperty and defaults to ‘linear’.

opening_icon_duration#

The duration of opening a new icon of the “marked” type.

opening_icon_duration is a NumericProperty and defaults to 0.1.

selected_segments#

The list of MDSegmentedButtonItem objects that are currently marked.

selected_segments is a ListProperty and defaults to [].

type#

Density can be used in denser UIs where space is limited. Density is only applied to the height. Each step down in density removes ‘4dp’ from the height.

New in version 2.0.0.

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

type is an OptionProperty and defaults to ‘large’.

selected_icon_color#

Color in (r, g, b, a) or string format of the icon of the marked segment.

New in version 2.0.0.

selected_icon_color is a ColorProperty and defaults to None.

get_marked_items() list#

Returns a list of active item objects.

get_items() list#

Returns a list of item objects.

adjust_segment_radius(*args) None#

Rounds off the first and last elements.

mark_item(segment_item: MDSegmentedButtonItem) None#

Fired when a segment element is clicked (on_release event).

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.segmentedbutton.segmentedbutton.MDSegmentButtonIcon(*args, **kwargs)#

Implements a icon for MDSegmentedButtonItem class.

New in version 2.0.0.

For more information, see in the MDIcon class documentation.

class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentButtonLabel(*args, **kwargs)#

Implements a label for MDSegmentedButtonItem class.

New in version 2.0.0.

For more information, see in the MDLabel class documentation.

ProgressIndicator#

#

Progress indicators show the status of a process in real time.

  • Use the same progress indicator for all instances of a process (like loading)

  • Two types: linear and circular

  • Never use them as decoration

  • They capture attention through motion

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/progress-indicator-types.png
  1. Linear progress indicator

  2. Circular progress indicator

Usage#
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDLinearProgressIndicator:
        size_hint_x: .5
        value: 50
        pos_hint: {'center_x': .5, 'center_y': .4}
'''


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

Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/linear-progress-indicator-usage.png
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDCircularProgressIndicator:
        size_hint: None, None
        size: "48dp", "48dp"
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


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


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

Linear progress indicators can be determinate or indeterminate.

Determinate linear progress indicator#

Determinate operations display the indicator increasing from 0 to 100% of the track, in sync with the process’s progress.

from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDLinearProgressIndicator:
        id: progress
        size_hint_x: .5
        type: "determinate"
        pos_hint: {'center_x': .5, 'center_y': .4}
'''


class Example(MDApp):
    def on_start(self):
        super().on_start()
        self.root.ids.progress.start()

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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/determinate-linear-progress-indicator.gif

Circular progress indicators can be determinate or indeterminate.

Indeterminate circular progress indicator#

Indeterminate operations display the indicator continually growing and shrinking along the track until the process is complete..

MDCircularProgressIndicator:
    size_hint: None, None
    size: "48dp", "48dp"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/circular-progress-indicator-usage.gif
Determinate circular progress indicator#
MDCircularProgressIndicator:
    size_hint: None, None
    size: "48dp", "48dp"
    determinate: True
    on_determinate_complete: print(args)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/determinate-circular-progress-indicator.gif
API break#
1.1.1 version#
MDProgressBar:
    value: 50
    color: app.theme_cls.accent_color
MDSpinner:
    size_hint: None, None
    size: dp(48), dp(48)
2.0.0 version#
MDLinearProgressIndicator:
    value: 50
    indicator_color: app.theme_cls.errorColor
MDCircularProgressIndicator:
    size_hint: None, None
    size: dp(48), dp(48)
API - kivymd.uix.progressindicator.progressindicator#
class kivymd.uix.progressindicator.progressindicator.MDLinearProgressIndicator(**kwargs)#

Implementation of the linear progress indicator.

For more information, see in the ThemableBehavior and ProgressBar classes documentation.

radius#

Progress line radius.

New in version 1.2.0.

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

reversed#

Reverse the direction the progressbar moves.

reversed is an BooleanProperty and defaults to False.

orientation#

Orientation of progressbar. Available options are: ‘horizontal ‘, ‘vertical’.

orientation is an OptionProperty and defaults to ‘horizontal’.

indicator_color#

Color of the active track.

Changed in version 2.0.0: Rename from color to indicator_color attribute.

indicator_color is an ColorProperty and defaults to None.

track_color#

Progress bar back color in (r, g, b, a) or string format.

New in version 1.0.0.

Changed in version 2.0.0: Rename from back_color to track_color attribute.

track_color is an ColorProperty and defaults to None.

running_determinate_transition#

Running transition.

Changed in version 2.0.0: Rename from running_transition to running_determinate_transition attribute.

running_determinate_transition is an StringProperty and defaults to ‘out_quart’.

catching_determinate_transition#

Catching transition.

Changed in version 2.0.0: Rename from catching_transition to catching_determinate_transition attribute.

catching_determinate_transition is an StringProperty and defaults to ‘out_quart’.

running_determinate_duration#

Running duration.

Changed in version 2.0.0: Rename from running_duration to running_determinate_duration attribute.

running_determinate_duration is an NumericProperty and defaults to 2.5.

catching_determinate_duration#

Catching duration.

running_duration is an NumericProperty and defaults to 0.8.

type#

Type of progressbar. Available options are: ‘indeterminate ‘, ‘determinate’.

type is an OptionProperty and defaults to None.

running_indeterminate_transition#

Running transition.

running_indeterminate_transition is an StringProperty and defaults to ‘in_cubic’.

catching_indeterminate_transition#

Catching transition.

catching_indeterminate_transition is an StringProperty and defaults to ‘out_quart’.

running_indeterminate_duration#

Running duration.

running_indeterminate_duration is an NumericProperty and defaults to 0.5.

catching_indeterminate_duration#

Catching duration.

catching_indeterminate_duration is an NumericProperty and defaults to 0.8.

check_size(*args) None#
start() None#

Start animation.

stop() None#

Stop animation.

running_away(*args) None#
catching_up(*args) None#
on_value(instance, value)#
class kivymd.uix.progressindicator.progressindicator.MDCircularProgressIndicator(**kwargs)#

Implementation of the circular progress indicator.

Changed in version 2.0.0: Rename MDSpinner to MDCircularProgressIndicator class.

For more information, see in the ThemableBehavior and Widget classes documentation.

It can be used either as an indeterminate indicator that loops while the user waits for something to happen, or as a determinate indicator.

Set determinate to True to activate determinate mode, and determinate_time to set the duration of the animation.

Events:
on_determinate_complete

The event is called at the end of the indicator loop in the determinate = True mode.

determinate#

Determinate value.

determinate is a BooleanProperty and defaults to False.

determinate_time#

Determinate time value.

determinate_time is a NumericProperty and defaults to 2.

line_width#

Progress line width of indicator.

line_width is a NumericProperty and defaults to dp(2.25).

active#

Use active to start or stop the indicator.

active is a BooleanProperty and defaults to True.

color#

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

color is a ColorProperty and defaults to None.

palette#

A set of colors. Changes with each completed indicator cycle.

palette is a ListProperty and defaults to [].

on__rotation_angle(*args)#
on_palette(instance, palette_list: list) None#

Fired when the palette value changes.

on_active(instance, value) None#

Fired when the active value changes.

on_determinate_complete(*args) None#

The event is fired at the end of the indicator loop in the determinate = True mode.

check_determinate(*args) None#

Fired when the class is initialized.

FitImage#

#
Example#
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDBoxLayout:
        radius: "36dp"
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint: .4, .8
        md_bg_color: self.theme_cls.onSurfaceVariantColor

        FitImage:
            source: "image.png"
            size_hint_y: .35
            pos_hint: {"top": 1}
            radius: "36dp", "36dp", 0, 0
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fitimage-round-corners.png
API - kivymd.uix.fitimage.fitimage#
class kivymd.uix.fitimage.fitimage.FitImage(**kwargs)#

Fit image class.

For more information, see in the AsyncImage and StencilBehavior classes documentation.

fit_mode#

Image will be stretched horizontally or vertically to fill the widget box, maintaining its aspect ratio. If the image has a different aspect ratio than the widget, then the image will be clipped to fit.

fit_mode is a OptionProperty and defaults to ‘cover’.

Badge#

#

New in version 2.0.0.

Badges show notifications, counts, or status information on navigation items and icons.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/badges.png
Example#
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDIcon:
        icon: "gmail"
        pos_hint: {'center_x': .5, 'center_y': .5}

        MDBadge:
            text: "12"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/badges-example.png
API - kivymd.uix.badge.badge#
class kivymd.uix.badge.badge.MDBadge(*args, **kwargs)#

Badge class.

New in version 2.0.0.

For more information see in the MDLabel class documentation.

Snackbar#

#

Snackbars provide brief messages about app processes at the bottom of the screen.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/snackbar.png
  • Snackbars shouldn’t interrupt the user’s experience

  • Usually appear at the bottom of the UI

  • Can disappear on their own or remain on screen until the user takes action

Usage#
MDSnackbar(
    MDSnackbarText(
        text="Text",
    ),
    y=dp(24),
    pos_hint={"center_x": 0.5},
    size_hint_x=0.5,
).open()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/snakbar-anatomy-detail.png
  1. Container

  2. Supporting text

  3. Action (optional)

  4. Icon (optional close affordance)

Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/snakbar-anatomy.png
Configurations#
1. Single line#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/snakbar-configurations-single-line.png
MDSnackbar(
    MDSnackbarText(
        text="Single-line snackbar",
    ),
    y=dp(24),
    pos_hint={"center_x": 0.5},
    size_hint_x=0.5,
).open()
2. Single-line snackbar with action#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/snakbar-configurations-single-line-with-action.png
MDSnackbar(
    MDSnackbarSupportingText(
        text="Single-line snackbar with action",
    ),
    MDSnackbarButtonContainer(
        MDSnackbarActionButton(
            MDSnackbarActionButtonText(
                text="Action button"
            ),
        ),
        pos_hint={"center_y": 0.5}
    ),
    y=dp(24),
    orientation="horizontal",
    pos_hint={"center_x": 0.5},
    size_hint_x=0.5,
).open()
3. Single-line snackbar with action and close buttons#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/snakbar-configurations-single-line-with-action-and-close-buttons.png
MDSnackbar(
    MDSnackbarSupportingText(
        text="Single-line snackbar with action and close buttons",
    ),
    MDSnackbarButtonContainer(
        MDSnackbarActionButton(
            MDSnackbarActionButtonText(
                text="Action button"
            ),
        ),
        MDSnackbarCloseButton(
            icon="close",
        ),
        pos_hint={"center_y": 0.5}
    ),
    y=dp(24),
    orientation="horizontal",
    pos_hint={"center_x": 0.5},
    size_hint_x=0.5,
).open()
4. Two-line snackbar with action and close buttons#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/snakbar-configurations-two-line-with-action-and-close-buttons.png
MDSnackbar(
    MDSnackbarText(
        text="Single-line snackbar",
    ),
    MDSnackbarSupportingText(
        text="with action and close buttons",
    ),
    MDSnackbarButtonContainer(
        MDSnackbarActionButton(
            MDSnackbarActionButtonText(
                text="Action button"
            ),
        ),
        MDSnackbarCloseButton(
            icon="close",
        ),
        pos_hint={"center_y": 0.5}
    ),
    y=dp(24),
    orientation="horizontal",
    pos_hint={"center_x": 0.5},
    size_hint_x=0.5,
).open()
5. Two-line snackbar with action and close buttons at the bottom#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/snakbar-configurations-two-line-with-action-and-close-buttons-bottom.png
MDSnackbar(
    MDSnackbarText(
        text="Single-line snackbar with action",
    ),
    MDSnackbarSupportingText(
        text="and close buttons at the bottom",
        padding=[0, 0, 0, dp(56)],
    ),
    MDSnackbarButtonContainer(
        Widget(),
        MDSnackbarActionButton(
            MDSnackbarActionButtonText(
                text="Action button"
            ),
        ),
        MDSnackbarCloseButton(
            icon="close",
        ),
    ),
    y=dp(124),
    pos_hint={"center_x": 0.5},
    size_hint_x=0.5,
    padding=[0, 0, "8dp", "8dp"],
).open()
API break#
1.1.1 version#
snackbar = Snackbar(
    text="First string",
    snackbar_x="10dp",
    snackbar_y="24dp",
)
snackbar.size_hint_x = (
    Window.width - (snackbar.snackbar_x * 2)
) / Window.width
snackbar.buttons = [
    MDFlatButton(
        text="Done",
        theme_text_color="Custom",
        text_color="#8E353C",
        on_release=snackbar.dismiss,
    ),
]
snackbar.open()
1.2.0 version#
MDSnackbar(
    MDLabel(
        text="First string",
    ),
    MDSnackbarActionButton(
        text="Done",
        theme_text_color="Custom",
        text_color="#8E353C",
    ),
    y=dp(24),
    pos_hint={"center_x": 0.5},
    size_hint_x=0.5,
    md_bg_color="#E8D8D7",
).open()
2.0.0 version#
MDSnackbar(
    MDSnackbarSupportingText(
        text="Single-line snackbar with action",
    ),
    MDSnackbarButtonContainer(
        MDSnackbarActionButton(
            MDSnackbarActionButtonText(
                text="Action button"
            ),
        ),
        pos_hint={"center_y": 0.5}
    ),
    y=dp(24),
    orientation="horizontal",
    pos_hint={"center_x": 0.5},
    size_hint_x=0.5,
    background_color=self.theme_cls.onPrimaryContainerColor,
).open()
API - kivymd.uix.snackbar.snackbar#
class kivymd.uix.snackbar.snackbar.MDSnackbarButtonContainer(*args, **kwargs)#

The class implements a container for placing snackbar buttons.

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

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.snackbar.snackbar.MDSnackbarCloseButton(**kwargs)#

Snackbar closed button class.

For more information, see in the MDIconButton class documentation.

class kivymd.uix.snackbar.snackbar.MDSnackbarActionButtonText(*args, **kwargs)#

The class implements the text for the MDSnackbarActionButton class.

Changed in version 2.2.0.

For more information, see in the MDButtonText class documentation.

class kivymd.uix.snackbar.snackbar.MDSnackbarActionButton(*args, **kwargs)#

Snackbar action button class.

For more information, see in the MDButton class documentation.

class kivymd.uix.snackbar.snackbar.MDSnackbar(*args, **kwargs)#

Snackbar class.

Changed in version 1.2.0: Rename BaseSnackbar to MDSnackbar class.

For more information, see in the MotionShackBehavior and MDCard and class documentation.

Events:
on_open

Fired when a snackbar opened.

on_dismiss

Fired when a snackbar closes.

duration#

The amount of time that the snackbar will stay on screen for.

duration is a NumericProperty and defaults to 3.

auto_dismiss#

Whether to use automatic closing of the snackbar or not.

auto_dismiss is a BooleanProperty and defaults to True.

radius#

Snackbar radius.

radius is a ListProperty and defaults to [dp(4), dp(4), dp(4), dp(4)]

background_color#

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

background_color is a ColorProperty and defaults to None.

dismiss(*args) None#

Dismiss the snackbar.

open() None#

Show the snackbar.

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)
on_open(*args) None#

Fired when a snackbar opened.

on_dismiss(*args) None#

Fired when a snackbar closed.

class kivymd.uix.snackbar.snackbar.MDSnackbarText(*args, **kwargs)#

The class implements the text.

For more information, see in the MDLabel class documentation.

class kivymd.uix.snackbar.snackbar.MDSnackbarSupportingText(*args, **kwargs)#

The class implements the supporting text.

For more information, see in the MDLabel class documentation.

Transition#

#

A set of classes for implementing transitions between application screens.

New in version 1.0.0.

Changing transitions#

You have multiple transitions available by default, such as:

  • MDFadeSlideTransition

    state one: the new screen closes the previous screen by lifting from the bottom of the screen and changing from transparent to non-transparent;

    state two: the current screen goes down to the bottom of the screen, passing from a non-transparent state to a transparent one, thus opening the previous screen;

Note

You cannot control the direction of a slide using the direction attribute.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/transition-md-fade-slide-transition.gif
API - kivymd.uix.transition.transition#
class kivymd.uix.transition.transition.MDTransitionBase#

TransitionBase is used to animate 2 screens within the MDScreenManager.

For more information, see in the TransitionBase class documentation.

start(instance_screen_manager: kivymd.uix.screenmanager.MDScreenManager) None#

(internal) Starts the transition. This is automatically called by the ScreenManager.

animated_hero_in() None#

Animates the flight of heroes from screen A to screen B.

animated_hero_out() None#

Animates the flight of heroes from screen B to screen A.

on_complete() None#

Override method. See :attr:`kivy.uix.screenmanager.TransitionBase.on_complete’.

class kivymd.uix.transition.transition.MDSwapTransition(**kwargs)#

Swap transition that looks like iOS transition when a new window appears on the screen.

class kivymd.uix.transition.transition.MDSlideTransition#

Slide Transition, can be used to show a new screen from any direction: left, right, up or down.

class kivymd.uix.transition.transition.MDFadeSlideTransition#

Slide Transition, can be used to show a new screen from any direction: left, right, up or down.

start(instance_screen_manager: kivymd.uix.screenmanager.MDScreenManager) None#

(internal) Starts the transition. This is automatically called by the ScreenManager.

on_progress(progression: float) None#

Text fields#

#

Text fields let users enter text into a UI.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields.png
  • Make sure text fields look interactive

  • Two types: filled and outlined

  • The text field’s state (blank, with input, error, etc) should be visible at a glance

  • Keep labels and error messages brief and easy to act on

  • Text fields commonly appear in forms and dialogs

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/available-fields.png
  1. Filled text field

  2. Outlined text field

Usage#
MDTextField:
    mode: "filled"

    MDTextFieldLeadingIcon:
        icon: "magnify"

    MDTextFieldHintText:
        text: "Hint text"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "persistent"

    MDTextFieldTrailingIcon:
        icon: "information"

    MDTextFieldMaxLengthText:
        max_text_length: 10
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-anatomy.png
Available types of text fields#
Filled mode#
MDTextField:
    mode: "filled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-filled-mode.png
Outlined mode#
MDTextField:
    mode: "outlined"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-outlined-mode.png
Example#
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDTextField:
        mode: "outlined"
        size_hint_x: None
        width: "240dp"
        pos_hint: {"center_x": .5, "center_y": .5}

        MDTextFieldLeadingIcon:
            icon: "account"

        MDTextFieldHintText:
            text: "Outlined"

        MDTextFieldHelperText:
            text: "Helper text"
            mode: "persistent"

        MDTextFieldTrailingIcon:
            icon: "information"

        MDTextFieldMaxLengthText:
            max_text_length: 10
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-example.png
API break#
1.2.0 version#
MDTextField:
    mode: "rectangle"
    hint_text: "Hint text"
    helper_text: "Helper text"
    helper_text_mode: "persistent"
    max_text_length: 10
    icon_right: "information"
2.0.0 version#

Note

The text field with the round type was removed in version 2.0.0.

MDTextField:
    mode: "outlined"

    MDTextFieldLeadingIcon:
        icon: "phone"

    MDTextFieldTrailingIcon:
        icon: "information"

    MDTextFieldHintText:
        text: "Hint text"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "persistent"

    MDTextFieldMaxLengthText:
        max_text_length: 10
API - kivymd.uix.textfield.textfield#
class kivymd.uix.textfield.textfield.AutoFormatTelephoneNumber#

Implements automatic formatting of the text entered in the text field according to the mask, for example ‘+38 (###) ### ## ##’.

Warning

This class has not yet been implemented and it is not recommended to use it yet.

isnumeric(value) bool#
do_backspace(*args) None#

Do backspace operation from the current cursor position.

field_filter(value, boolean) None#
format(value) None#
class kivymd.uix.textfield.textfield.Validator#

Container class for various validation methods.

datetime_date#

The last valid date as a <class ‘datetime.date’> object.

datetime_date is an ObjectProperty and defaults to None.

date_interval#

The date interval that is valid for input. Can be entered as <class ‘datetime.date’> objects or a string format. Both values or just one value can be entered.

In string format, must follow the current date_format. Example: Given date_format -> “mm/dd/yyyy” Input examples -> “12/31/1900”, “12/31/2100” or “12/31/1900”, None.

date_interval is an ListProperty and defaults to [None, None].

date_format#

Format of date strings that will be entered. Available options are: ‘dd/mm/yyyy’, ‘mm/dd/yyyy’, ‘yyyy/mm/dd’.

date_format is an OptionProperty and defaults to None.

is_email_valid(text: str) bool#

Checks the validity of the email.

is_time_valid(text: str) bool#

Checks the validity of the time.

is_date_valid(text: str) bool#

Checks the validity of the date.

on_date_interval(*args) None#

Default event handler for date_interval input.

class kivymd.uix.textfield.textfield.BaseTextFieldLabel(*args, **kwargs)#

Base texture for MDTextField class (helper text, max length, hint text).

For more information, see in the MDLabel class documentation.

New in version 2.0.0.

text_color_normal#

Text color in (r, g, b, a) or string format when text field is out of focus.

New in version 1.0.0.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_color_normal to text_color_normal.

MDTextField:
    mode: "filled"

    MDTextFieldHintText:
        text: "Hint text color normal"
        text_color_normal: "brown"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-text-color-normal.png

text_color_normal is an ColorProperty and defaults to None.

text_color_focus#

Text color in (r, g, b, a) or string format when the text field has focus.

New in version 1.0.0.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_color_focus to text_color_focus.

MDTextField:

    MDTextFieldHelperText:
        text: "Helper text color focus"
        text_color_focus: "brown"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-text-color-focus.png

text_color_focus is an ColorProperty and defaults to None.

class kivymd.uix.textfield.textfield.MDTextFieldHelperText(*args, **kwargs)#

Implements the helper text label.

For more information, see in the BaseTextFieldLabel class documentation.

New in version 2.0.0.

mode#

Helper text mode. Available options are: ‘on_error’, ‘persistent’, ‘on_focus’.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_mode to mode.

On focus#
MDTextField:
    mode: "filled"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "on_focus"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-helper-text-mode-on-focus.gif
On error#
MDTextField:
    mode: "filled"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "on_error"

    MDTextFieldMaxLengthText:
        max_text_length: 5
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-helper-text-mode-on-error.gif
Persistent#
MDTextField:
    mode: "filled"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "persistent"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-helper-text-mode-persistent.gif

mode is an OptionProperty and defaults to ‘on_focus’.

class kivymd.uix.textfield.textfield.MDTextFieldMaxLengthText(*args, **kwargs)#

Implements the max length text label.

For more information, see in the BaseTextFieldLabel class documentation.

New in version 2.0.0.

max_text_length#

Maximum allowed value of characters in a text field.

Changed in version 2.0.0: The property was moved from class:~MDTextField.

MDTextField:
    mode: "filled"

    MDTextFieldMaxLengthText:
        max_text_length: 10
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-max-text-length.png

max_text_length is an NumericProperty and defaults to None.

class kivymd.uix.textfield.textfield.MDTextFieldHintText(*args, **kwargs)#

Implements the hint text label.

For more information, see in the BaseTextFieldLabel class documentation.

New in version 2.0.0.

MDTextField:
    mode: "filled"

    MDTextFieldHintText:
        text: "Hint text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-hint-text.gif
class kivymd.uix.textfield.textfield.BaseTextFieldIcon(*args, **kwargs)#

Base texture for MDTextField class (helper text, max length, hint text).

For more information, see in the MDIcon class documentation.

Changed in version 2.0.0.

icon_color_normal#

Icon color in (r, g, b, a) or string format when text field is out of focus.

New in version 1.0.0.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from icon_right_color_normal/icon_left_color_normal to icon_color_normal.

MDTextField:
    mode: "filled"

    MDTextFieldLeadingIcon:
        icon: "phone"
        theme_icon_color: "Custom"
        icon_color_normal: "lightgreen"

    MDTextFieldHintText:
        text: "Leading icon color normal"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-leading-icon-color-normal.png

icon_color_normal is an ColorProperty and defaults to None.

icon_color_focus#

Icon color in (r, g, b, a) or string format when the text field has focus.

New in version 1.0.0.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from icon_right_color_focus/icon_left_color_focus ` to `icon_color_focus.

MDTextField:
    mode: "filled"

    MDTextFieldLeadingIcon:
        icon: "phone"
        theme_icon_color: "Custom"
        icon_color_focus: "lightgreen"

    MDTextFieldHintText:
        text: "Leading icon color focus"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-leading-icon-color-focus.png

icon_color_focus is an ColorProperty and defaults to None.

class kivymd.uix.textfield.textfield.MDTextFieldLeadingIcon(*args, **kwargs)#

Implements the leading icon.

For more information, see in the BaseTextFieldIcon class documentation.

New in version 2.0.0.

MDTextField:
    mode: "filled"

    MDTextFieldLeadingIcon:
        icon: "phone"

    MDTextFieldHintText:
        text: "Field with leading icon"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-leading-icon.png
class kivymd.uix.textfield.textfield.MDTextFieldTrailingIcon(*args, **kwargs)#

Implements the trailing icon.

For more information, see in the BaseTextFieldIcon class documentation.

New in version 2.0.0.

MDTextField:
    mode: "filled"

    MDTextFieldTrailingIcon:
        icon: "phone"

    MDTextFieldHintText:
        text: "Field with trailing icon"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-trailing-icon.png
class kivymd.uix.textfield.textfield.MDTextField(*args, **kwargs)#

Textfield class.

For more information, see in the DeclarativeBehavior and BackgroundColorBehavior and ThemableBehavior and TextInput and Validator and AutoFormatTelephoneNumber and StateLayerBehavior classes documentation.

font_style#

Name of the style for the input text.

New in version 2.0.0.

See also

Font style names

font_style is an StringProperty and defaults to ‘Body’.

role#

Role of font style.

New in version 2.0.0.

See also

Font style roles

role is an StringProperty and defaults to ‘large’.

mode#

Text field mode. Available options are: ‘outlined’, ‘filled’.

mode is an OptionProperty and defaults to ‘outlined’.

error_color#

Error color in (r, g, b, a) or string format for required = True or when the text field is in error state.

error_color is an ColorProperty and defaults to None.

error#

If True, then the text field goes into error mode.

error is an BooleanProperty and defaults to False.

text_color_normal#

Text color in (r, g, b, a) or string format when text field is out of focus.

New in version 1.0.0.

MDTextField:
    theme_text_color: "Custom"
    text_color_normal: "green"
    text: "Text color normal"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-text-color-normal.png

text_color_normal is an ColorProperty and defaults to None.

text_color_focus#

Text color in (r, g, b, a) or string format when text field has focus.

New in version 1.0.0.

MDTextField:
    theme_text_color: "Custom"
    text_color_focus: "green"
    text: "Text color focus"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-text-color-focus.png

text_color_focus is an ColorProperty and defaults to None.

radius#

The corner radius for a text field in filled/outlined mode.

radius is a VariableListProperty and defaults to [dp(4), dp(4), 0, 0].

required#

Required text. If True then the text field requires text.

required is an BooleanProperty and defaults to False.

line_color_normal#

Line color normal (active indicator) in (r, g, b, a) or string format.

MDTextField:
    mode: "filled"
    theme_line_color: "Custom"
    line_color_normal: "green"

    MDTextFieldHelperText:
        text: "Line color normal"
        mode: "persistent"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-line-color-normal.png

line_color_normal is an ColorProperty and defaults to None.

line_color_focus#

Line color focus (active indicator) in (r, g, b, a) or string format.

MDTextField:
    mode: "filled"
    theme_line_color: "Custom"
    line_color_focus: "green"

    MDTextFieldHelperText:
        text: "Line color focus"
        mode: "persistent"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-line-color-focus.png

line_color_focus is an ColorProperty and defaults to None.

fill_color_normal#

Fill background color in (r, g, b, a) or string format in ‘fill’ mode when] text field is out of focus.

MDTextField:
    mode: "filled"
    theme_bg_color: "Custom"
    fill_color_normal: 0, 1, 0, .2

    MDTextFieldHelperText:
        text: "Fill color normal"
        mode: "persistent"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-fill-color-normal.png

fill_color_normal is an ColorProperty and defaults to None.

fill_color_focus#

Fill background color in (r, g, b, a) or string format in ‘fill’ mode when the text field has focus.

MDTextField:
    mode: "filled"
    theme_bg_color: "Custom"
    fill_color_focus: 0, 1, 0, .2

    MDTextFieldHelperText:
        text: "Fill color focus"
        mode: "persistent"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-fill-color-focus.png

fill_color_focus is an ColorProperty and defaults to None.

max_height#

Maximum height of the text box when multiline = True.

MDTextField:
    mode: "filled"
    max_height: "200dp"
    multiline: True

    MDTextFieldHelperText:
        text: "multiline=True"
        mode: "persistent"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-multiline.gif

max_height is a NumericProperty and defaults to 0.

phone_mask#

This property has not yet been implemented and it is not recommended to use it yet.

phone_mask is a StringProperty and defaults to ‘’.

validator#

The type of text field for entering Email, time, etc. Automatically sets the type of the text field as “error” if the user input does not match any of the set validation types. Available options are: ‘date’, ‘email’, ‘time’.

When using ‘date’, date_format must be defined.

New in version 1.1.0.

MDTextField:
    mode: "filled"
    validator: "email"

    MDTextFieldHintText:
        text: "Email"

    MDTextFieldHelperText:
        text: "user@gmail.com"
        mode: "persistent"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-email-validator.png
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDBoxLayout:
        orientation: "vertical"
        spacing: "20dp"
        adaptive_height: True
        size_hint_x: .8
        pos_hint: {"center_x": .5, "center_y": .5}

        MDTextField:
            validator: "date"
            date_format: "dd/mm/yyyy"

            MDTextFieldHintText:
                text: "Date dd/mm/yyyy without limits"

            MDTextFieldHelperText:
                text: "Enter a valid dd/mm/yyyy date"

        MDTextField:
            validator: "date"
            date_format: "mm/dd/yyyy"

            MDTextFieldHintText:
                text: "Date mm/dd/yyyy without limits"

            MDTextFieldHelperText:
                text: "Enter a valid mm/dd/yyyy date"

        MDTextField:
            validator: "date"
            date_format: "yyyy/mm/dd"

            MDTextFieldHintText:
                text: "Date yyyy/mm/dd without limits"

            MDTextFieldHelperText:
                text: "Enter a valid yyyy/mm/dd date"

        MDTextField:
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: "01/01/1900", "01/01/2100"

            MDTextFieldHintText:
                text: "Date dd/mm/yyyy in [01/01/1900, 01/01/2100] interval"

            MDTextFieldHelperText:
                text: "Enter a valid dd/mm/yyyy date"

        MDTextField:
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: "01/01/1900", None

            MDTextFieldHintText:
                text: "Date dd/mm/yyyy in [01/01/1900, None] interval"

            MDTextFieldHelperText:
                text: "Enter a valid dd/mm/yyyy date"

        MDTextField:
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: None, "01/01/2100"

            MDTextFieldHintText:
                text: "Date dd/mm/yyyy in [None, 01/01/2100] interval"

            MDTextFieldHelperText:
                text: "Enter a valid dd/mm/yyyy date"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-validator-date.png

validator is an OptionProperty and defaults to None.

update_colors(theme_manager: kivymd.theming.ThemeManager, theme_color: str) None#

Fired when the primary_palette or theme_style value changes.

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)
set_texture_color(texture, canvas_group, color: list, error: bool = False) None#

Animates the color of the leading/trailing icons/hint/helper/max length text.

set_pos_hint_text(y: float, x: float) None#

Animates the x-axis width and y-axis height of the hint text.

set_hint_text_font_size() None#

Animates the font size of the hint text.

set_space_in_line(left_width: float | int, right_width: float | int) None#

Animates the length of the right line of the text field for the hint text.

set_max_text_length() None#

Fired when text is entered into a text field. Set max length text and updated max length texture.

set_text(instance, text: str) None#

Fired when text is entered into a text field.

on_focus(instance, focus: bool) None#

Fired when the focus value changes.

on_disabled(instance, disabled: bool) None#

Fired when the disabled value changes.

on_error(instance, error: bool) None#

Changes the primary colors of the text box to match the error value (text field is in an error state or not).

on_height(instance, value_height: float) None#

DropdownItem#

#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dropdown-item.png
Usage#
from kivy.lang import Builder
from kivymd.uix.menu import MDDropdownMenu

from kivymd.app import MDApp

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

    MDDropDownItem:
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.open_menu(self)

        MDDropDownItemText:
            id: drop_text
            text: "Item"
'''


class Example(MDApp):
    def open_menu(self, item):
        menu_items = [
            {
                "text": f"{i}",
                "on_release": lambda x=f"Item {i}": self.menu_callback(x),
            } for i in range(5)
        ]
        MDDropdownMenu(caller=item, items=menu_items).open()

    def menu_callback(self, text_item):
        self.root.ids.drop_text.text = text_item

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


Example().run()
API break#
1.2.0 version#
MDDropDownItem:
    text: 'Item'
    on_release: print(*args)
2.0.0 version#
MDDropDownItem:
    on_release:  print(*args)

    MDDropDownItemText:
        text: "Item text"
API - kivymd.uix.dropdownitem.dropdownitem#
class kivymd.uix.dropdownitem.dropdownitem.MDDropDownItemText(*args, **kwargs)#

Base texture for MDDropDownItem class (item text).

For more information, see in the MDLabel class documentation.

New in version 2.0.0.

class kivymd.uix.dropdownitem.dropdownitem.MDDropDownItem(*args, **kwargs)#

Dropdown item class.

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

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)
update_text_item(instance, value) None#

Updates the text of the item.

on_disabled(instance, value) None#

Fired when the values of disabled change.

on__drop_down_text(instance, value) None#

Fired when the values of _drop_down_text change.

Appbar#

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

KivyMD provides the following bar positions for use:

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

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-available-types.png
  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#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-anatomy.png
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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-center-aligned.png
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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-small.png
3. Medium#
MDTopAppBar:
    type: "medium"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-medium.png
4. Large#
MDTopAppBar:
    type: "large"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-large.png
BottomAppBar#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/app-bar-bottom-m3.png
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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-app-bar-m3-style-1.png
Add action items#
#:import MDActionBottomAppBarButton kivymd.uix.appbar.MDActionBottomAppBarButton


MDScreen:

    MDBottomAppBar:
        action_items:
            [
            MDActionBottomAppBarButton(icon="gmail"),
            MDActionBottomAppBarButton(icon="label-outline"),
            MDActionBottomAppBarButton(icon="bookmark"),
            ]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-app-bar-m3-style-2.png
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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-app-bar-m3-style-3.gif
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,
                    }
                )

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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-app-bar-m3-style-4.gif
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)

Dialog#

#

Dialogs provide important prompts in a user flow.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dialog-preview.png
  • Use dialogs to make sure users act on information

  • Two types: basic and full-screen (full-screen not provided in KivyMD)

  • Should be dedicated to completing a single task

  • Can also display information relevant to the task

  • Commonly used to confirm high-risk actions like deleting progress

Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dialog-anatomy.png
Example#
from kivy.lang import Builder
from kivy.uix.widget import Widget

from kivymd.app import MDApp
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.dialog import (
    MDDialog,
    MDDialogIcon,
    MDDialogHeadlineText,
    MDDialogSupportingText,
    MDDialogButtonContainer,
    MDDialogContentContainer,
)
from kivymd.uix.divider import MDDivider
from kivymd.uix.list import (
    MDListItem,
    MDListItemLeadingIcon,
    MDListItemSupportingText,
)

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_alert_dialog()

        MDButtonText:
            text: "Show dialog"
'''


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

    def show_alert_dialog(self):
        MDDialog(
            # ----------------------------Icon-----------------------------
            MDDialogIcon(
                icon="refresh",
            ),
            # -----------------------Headline text-------------------------
            MDDialogHeadlineText(
                text="Reset settings?",
            ),
            # -----------------------Supporting text-----------------------
            MDDialogSupportingText(
                text="This will reset your app preferences back to their "
                "default settings. The following accounts will also "
                "be signed out:",
            ),
            # -----------------------Custom content------------------------
            MDDialogContentContainer(
                MDDivider(),
                MDListItem(
                    MDListItemLeadingIcon(
                        icon="gmail",
                    ),
                    MDListItemSupportingText(
                        text="KivyMD-library@yandex.com",
                    ),
                    theme_bg_color="Custom",
                    md_bg_color=self.theme_cls.transparentColor,
                ),
                MDListItem(
                    MDListItemLeadingIcon(
                        icon="gmail",
                    ),
                    MDListItemSupportingText(
                        text="kivydevelopment@gmail.com",
                    ),
                    theme_bg_color="Custom",
                    md_bg_color=self.theme_cls.transparentColor,
                ),
                MDDivider(),
                orientation="vertical",
            ),
            # ---------------------Button container------------------------
            MDDialogButtonContainer(
                Widget(),
                MDButton(
                    MDButtonText(text="Cancel"),
                    style="text",
                ),
                MDButton(
                    MDButtonText(text="Accept"),
                    style="text",
                ),
                spacing="8dp",
            ),
            # -------------------------------------------------------------
        ).open()


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

Warning

Do not try to use the MDDialog widget in KV files.

API break#
1.2.0 version#
from kivy.uix.widget import Widget

from kivymd.app import MDApp
from kivymd.uix.button import MDFlatButton
from kivymd.uix.dialog import MDDialog


class Example(MDApp):
    def build(self):
        return Widget()

    def on_start(self):
        super().on_start()
        MDDialog(
            title="Discard draft?",
            buttons=[
                MDFlatButton(
                    text="CANCEL",
                    theme_text_color="Custom",
                    text_color=self.theme_cls.primary_color,
                ),
                MDFlatButton(
                    text="DISCARD",
                    theme_text_color="Custom",
                    text_color=self.theme_cls.primary_color,
                ),
            ],
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dialog-api-break-1-2-0.png
from kivy.uix.widget import Widget

from kivymd.app import MDApp
from kivymd.uix.button import MDFlatButton
from kivymd.uix.dialog import MDDialog


class Example(MDApp):
    def build(self):
        return Widget()

    def on_start(self):
        super().on_start()
        MDDialog(
            title="Discard draft?",
            text="This will reset your device to its default factory settings.",
            buttons=[
                MDFlatButton(
                    text="CANCEL",
                    theme_text_color="Custom",
                    text_color=self.theme_cls.primary_color,
                ),
                MDFlatButton(
                    text="DISCARD",
                    theme_text_color="Custom",
                    text_color=self.theme_cls.primary_color,
                ),
            ],
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/2-dialog-api-break-1-2-0.png
from kivy.lang import Builder
from kivy.properties import StringProperty
from kivy.uix.widget import Widget

from kivymd import images_path
from kivymd.app import MDApp
from kivymd.uix.dialog import MDDialog
from kivymd.uix.list import OneLineAvatarListItem

KV = '''
<Item>

    ImageLeftWidget:
        source: root.source
'''


class Item(OneLineAvatarListItem):
    divider = None
    source = StringProperty()


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

    def on_start(self):
        super().on_start()
        MDDialog(
            title="Set backup account",
            type="simple",
            items=[
                Item(text="user01@gmail.com", source=f"{images_path}/logo/kivymd-icon-128.png"),
                Item(text="user02@gmail.com", source="data/logo/kivy-icon-128.png"),
            ],
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/3-dialog-api-break-1-2-0.png
2.2.0 version#
from kivy.uix.widget import Widget

from kivymd.uix.widget import MDWidget
from kivymd.app import MDApp
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.dialog import MDDialog, MDDialogHeadlineText, MDDialogButtonContainer


class Example(MDApp):
    def build(self):
        return MDWidget(md_bg_color=self.theme_cls.backgroundColor)

    def on_start(self):
        super().on_start()
        MDDialog(
            MDDialogHeadlineText(
                text="Discard draft?",
                halign="left",
            ),
            MDDialogButtonContainer(
                Widget(),
                MDButton(
                    MDButtonText(text="Cancel"),
                    style="text",
                ),
                MDButton(
                    MDButtonText(text="Discard"),
                    style="text",
                ),
                spacing="8dp",
            ),
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dialog-api-break-2-2-0.png
from kivy.uix.widget import Widget

from kivymd.uix.widget import MDWidget
from kivymd.app import MDApp
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.dialog import MDDialog, MDDialogHeadlineText, MDDialogButtonContainer


class Example(MDApp):
    def build(self):
        return MDWidget(md_bg_color=self.theme_cls.backgroundColor)

    def on_start(self):
        super().on_start()
        MDDialog(
            MDDialogHeadlineText(
                text="Discard draft?",
                halign="left",
            ),
            MDDialogSupportingText(
                text="This will reset your device to its default factory settings.",
                halign="left",
            ),
            MDDialogButtonContainer(
                Widget(),
                MDButton(
                    MDButtonText(text="Cancel"),
                    style="text",
                ),
                MDButton(
                    MDButtonText(text="Discard"),
                    style="text",
                ),
                spacing="8dp",
            ),
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/2-dialog-api-break-2-2-0.png
from kivymd import images_path
from kivymd.uix.widget import MDWidget
from kivymd.app import MDApp
from kivymd.uix.dialog import (
    MDDialog,
    MDDialogHeadlineText,
    MDDialogContentContainer,
)
from kivymd.uix.list import (
    MDListItem,
    MDListItemLeadingAvatar,
    MDListItemSupportingText,
)


class Example(MDApp):
    def build(self):
        return MDWidget(md_bg_color=self.theme_cls.backgroundColor)

    def on_start(self):
        super().on_start()
        MDDialog(
            MDDialogHeadlineText(
                text="Set backup account",
                halign="left",
            ),
            MDDialogContentContainer(
                MDListItem(
                    MDListItemLeadingAvatar(
                        source=f"{images_path}/logo/kivymd-icon-128.png",
                    ),
                    MDListItemSupportingText(
                        text="user01@gmail.com",
                    ),
                    theme_bg_color="Custom",
                    md_bg_color=self.theme_cls.transparentColor,
                ),
                MDListItem(
                    MDListItemLeadingAvatar(
                        source="data/logo/kivy-icon-128.png",
                    ),
                    MDListItemSupportingText(
                        text="user01@gmail.com",
                    ),
                    theme_bg_color="Custom",
                    md_bg_color=self.theme_cls.transparentColor,
                ),
                orientation="vertical",
            ),
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/3-dialog-api-break-2-2-0.png
API - kivymd.uix.dialog.dialog#
class kivymd.uix.dialog.dialog.MDDialog(*args, **kwargs)#

Dialog class.

For more information, see in the MDCard and MotionDialogBehavior classes documentation.

Events:
on_pre_open:

Fired before the MDDialog is opened. When this event is fired MDDialog is not yet added to window.

on_open:

Fired when the MDDialog is opened.

on_pre_dismiss:

Fired before the MDDialog is closed.

on_dismiss:

Fired when the MDDialog is closed. If the callback returns True, the dismiss will be canceled.

width_offset#

Dialog offset from device width.

width_offset is an NumericProperty and defaults to dp(48).

radius#

Dialog corners rounding value.

radius is an VariableListProperty and defaults to [dp(28), dp(28), dp(28), dp(28)].

scrim_color#

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

scrim_color is a ColorProperty and defaults to [0, 0, 0, 0.5].

auto_dismiss#

This property determines if the dialog is automatically dismissed when the user clicks outside it.

..versionadded:: 2.0.0

auto_dismiss is a BooleanProperty and defaults to True.

update_width(*args) None#
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)
open() None#

Show the dialog.

on_pre_open(*args) None#

Fired when a dialog pre opened.

on_open(*args) None#

Fired when a dialog opened.

on_dismiss(*args) None#

Fired when a dialog dismiss.

on_pre_dismiss(*args) None#

Fired when a dialog pre-dismiss.

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

dismiss(*args) None#

Closes the dialog.

class kivymd.uix.dialog.dialog.MDDialogIcon(*args, **kwargs)#

The class implements an icon.

For more information, see in the MDIcon class documentation.

class kivymd.uix.dialog.dialog.MDDialogHeadlineText(*args, **kwargs)#

The class implements the headline text.

For more information, see in the MDLabel class documentation.

class kivymd.uix.dialog.dialog.MDDialogSupportingText(*args, **kwargs)#

The class implements the supporting text.

For more information, see in the MDLabel class documentation.

class kivymd.uix.dialog.dialog.MDDialogContentContainer(*args, **kwargs)#

The class implements the container for custom widgets.

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

class kivymd.uix.dialog.dialog.MDDialogButtonContainer(*args, **kwargs)#

The class implements a container for placing dialog buttons.

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

SelectionControls#

#

Selection controls allow the user to select options.

KivyMD provides the following selection controls classes for use:

MDCheckbox#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox.png
Usage#
from kivy.lang import Builder

from kivymd.app import MDApp


KV = '''
MDFloatLayout:

    MDCheckbox:
        size_hint: None, None
        size: "48dp", "48dp"
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


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


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

Note

Be sure to specify the size of the checkbox. By default, it is (dp(48), dp(48)), but the ripple effect takes up all the available space.

Control state#
MDCheckbox:
    on_active: app.on_checkbox_active(*args)
def on_checkbox_active(self, checkbox, value):
    if value:
        print('The checkbox', checkbox, 'is active', 'and', checkbox.state, 'state')
    else:
        print('The checkbox', checkbox, 'is inactive', 'and', checkbox.state, 'state')
MDCheckbox with group#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<Check@MDCheckbox>:
    group: 'group'
    size_hint: None, None
    size: dp(48), dp(48)


MDFloatLayout:

    Check:
        active: True
        pos_hint: {'center_x': .4, 'center_y': .5}

    Check:
        pos_hint: {'center_x': .6, 'center_y': .5}
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-group.gif
Parent and child checkboxes#

Checkboxes can have a parent-child relationship with other checkboxes. When the parent checkbox is checked, all child checkboxes are checked. If a parent checkbox is unchecked, all child checkboxes are unchecked. If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox.

Usage#
MDCheckbox:
    group: "root"  # this is a required name for the parent checkbox group

MDCheckbox:
    group: "child"  # this is a required name for a group of child checkboxes

MDCheckbox:
    group: "child"  # this is a required name for a group of child checkboxes
Example#
from kivy.lang import Builder
from kivy.properties import StringProperty

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

KV = '''
<CheckItem>
    adaptive_height: True

    MDCheckbox:
        group: root.group

    MDLabel:
        text: root.text
        adaptive_height: True
        padding_x: "12dp"
        pos_hint: {"center_y": .5}


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

    MDBoxLayout:
        orientation: "vertical"
        adaptive_height: True
        padding: "12dp", "36dp", 0, 0
        spacing: "12dp"

        CheckItem:
            text: "Recieve emails"
            group: "root"

        MDBoxLayout:
            orientation: "vertical"
            adaptive_height: True
            padding: "24dp", 0, 0, 0
            spacing: "12dp"

            CheckItem:
                text: "Daily"
                group: "child"

            CheckItem:
                text: "Weekly"
                group: "child"

            CheckItem:
                text: "Monthly"
                group: "child"

    MDWidget:
'''


class CheckItem(MDBoxLayout):
    text = StringProperty()
    group = StringProperty()


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-parent-child.gif
MDSwitch#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch.png
Usage#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDFloatLayout:

    MDSwitch:
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


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


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

Note

Control state of MDSwitch same way as in MDCheckbox.

API - kivymd.uix.selectioncontrol.selectioncontrol#
class kivymd.uix.selectioncontrol.selectioncontrol.MDCheckbox(**kwargs)#

Checkbox class.

For more information, see in the StateLayerBehavior and CircularRippleBehavior and ScaleBehavior and ToggleButtonBehavior and MDIcon classes documentation.

active#

Indicates if the checkbox is active or inactive.

active is a BooleanProperty and defaults to False.

checkbox_icon_normal#

Background icon of the checkbox used for the default graphical representation when the checkbox is not pressed.

checkbox_icon_normal is a StringProperty and defaults to ‘checkbox-blank-outline’.

checkbox_icon_down#

Background icon of the checkbox used for the default graphical representation when the checkbox is pressed.

checkbox_icon_down is a StringProperty and defaults to ‘checkbox-marked’.

radio_icon_normal#

Background icon (when using the group option) of the checkbox used for the default graphical representation when the checkbox is not pressed.

radio_icon_normal is a StringProperty and defaults to ‘checkbox-blank-circle-outline’.

radio_icon_down#

Background icon (when using the group option) of the checkbox used for the default graphical representation when the checkbox is pressed.

radio_icon_down is a StringProperty and defaults to ‘checkbox-marked-circle’.

color_active#

Color in (r, g, b, a) or string format when the checkbox is in the active state.

New in version 1.0.0.

MDCheckbox:
    color_active: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-color-active.png

color_active is a ColorProperty and defaults to None.

color_inactive#

Color in (r, g, b, a) or string format when the checkbox is in the inactive state.

New in version 1.0.0.

MDCheckbox:
    color_inactive: "blue"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-color-inactive.png

color_inactive is a ColorProperty and defaults to None.

color_disabled#

Color in (r, g, b, a) or string format when the checkbox is in the disabled state.

New in version 2.0.0: Use color_disabled instead.

color_disabled is a ColorProperty and defaults to None.

disabled_color#

Color in (r, g, b, a) or string format when the checkbox is in the disabled state.

Deprecated since version 2.0.0: Use color_disabled instead.

disabled_color is a ColorProperty and defaults to None.

selected_color#

Color in (r, g, b, a) or string format when the checkbox is in the active state.

Deprecated since version 1.0.0: Use color_active instead.

selected_color is a ColorProperty and defaults to None.

unselected_color#

Color in (r, g, b, a) or string format when the checkbox is in the inactive state.

Deprecated since version 1.0.0: Use color_inactive instead.

unselected_color is a ColorProperty and defaults to None.

update_icon(*args) None#

Fired when the values of checkbox_icon_normal and checkbox_icon_down and radio_icon_normal and group change.

set_root_active() None#
set_child_active(active: bool)#
on_state(*args) None#

Fired when the values of state change.

on_active(*args) None#

Fired when the values of active change.

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

class kivymd.uix.selectioncontrol.selectioncontrol.MDSwitch(**kwargs)#

Switch class.

For more information, see in the StateLayerBehavior and MDFloatLayout classes documentation.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

ripple_effect#

Allows or does not allow the ripple effect when activating/deactivating the switch.

New in version 2.0.0.

ripple_effect is a BooleanProperty and defaults to True.

active#

Indicates if the switch is active or inactive.

active is a BooleanProperty and defaults to False.

icon_active#

Thumb icon when the switch is in the active state (only M3 style).

New in version 1.0.0.

MDSwitch:
    active: True
    icon_active: "check"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-icon-active.png

icon_active is a StringProperty and defaults to ‘’.

icon_inactive#

Thumb icon when the switch is in an inactive state (only M3 style).

New in version 1.0.0.

MDSwitch:
    icon_inactive: "close"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-icon-inactive.png

icon_inactive is a StringProperty and defaults to ‘’.

icon_active_color#

Thumb icon color in (r, g, b, a) or string format when the switch is in the active state (only M3 style).

New in version 1.0.0.

MDSwitch:
    active: True
    icon_active: "check"
    icon_active_color: "white"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-icon-active-color.png

icon_active_color is a ColorProperty and defaults to None.

icon_inactive_color#

Thumb icon color in (r, g, b, a) or string format when the switch is in an inactive state (only M3 style).

New in version 1.0.0.

MDSwitch:
    icon_inactive: "close"
    icon_inactive_color: "grey"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-icon-inactive-color.png

icon_inactive_color is a ColorProperty and defaults to None.

thumb_color_active#

The color in (r, g, b, a) or string format of the thumb when the switch is active.

New in version 1.0.0.

MDSwitch:
    active: True
    thumb_color_active: "brown"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-thumb-color-active.png

thumb_color_active is an ColorProperty and default to None.

thumb_color_inactive#

The color in (r, g, b, a) or string format of the thumb when the switch is inactive.

New in version 1.0.0.

MDSwitch:
    thumb_color_inactive: "brown"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-thumb-color-inactive.png

thumb_color_inactive is an ColorProperty and default to None.

thumb_color_disabled#

The color in (r, g, b, a) or string format of the thumb when the switch is in the disabled state.

MDSwitch:
    active: True
    thumb_color_disabled: "brown"
    disabled: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-thumb-color-disabled.png

thumb_color_disabled is an ColorProperty and default to None.

track_color_active#

The color in (r, g, b, a) or string format of the track when the switch is active.

MDSwitch:
    active: True
    track_color_active: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-track-color-active.png

track_color_active is an ColorProperty and default to None.

track_color_inactive#

The color in (r, g, b, a) or string format of the track when the switch is inactive.

New in version 1.0.0.

MDSwitch:
    track_color_inactive: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-track-color-inactive.png

track_color_inactive is an ColorProperty and default to None.

track_color_disabled#

The color in (r, g, b, a) or string format of the track when the switch is in the disabled state.

MDSwitch:
    track_color_disabled: "lightgrey"
    disabled: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-track-color-disabled.png

track_color_disabled is an ColorProperty and default to None.

line_color_disabled#

The color of the outline in the disabled state

New in version 2.0.0.

line_color_disabled is an ColorProperty and defaults to None.

set_icon(instance_switch, icon_value: str) None#

Fired when the values of icon_active and icon_inactive change.

on_line_color(instance, value) None#

Fired when the values of line_color change.

on_active(instance_switch, active_value: bool) None#

Fired when the values of active change.

on_thumb_down() None#

Fired at the on_touch_down event of the Thumb object. Indicates the state of the switch “on/off” by an animation of increasing the size of the thumb.

TimePicker#

#

Time pickers help users select and set a specific time.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker.png
  • Time pickers are modal and cover the main content

  • Two types: dial and input

  • Users can select hours, minutes, or periods of time

  • Make sure time can easily be selected by hand on a mobile device

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-types.png
  1. Vertical dial time picker

  2. Horizontal dial time picker

  3. Time picker input

KivyMD provides the following date pickers classes for use:

MDTimePickerDialVertical#

Time pickers allow people to enter a specific time value. They’re displayed in dialogs and can be used to select hours, minutes, or periods of time.

They can be used for a wide range of scenarios. Common use cases include:

  • Setting an alarm

  • Scheduling a meeting

Time pickers are not ideal for nuanced or granular time selection, such as milliseconds for a stopwatch application.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/vertical-time-picker-preview.gif
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.pickers import MDTimePickerDialVertical

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_time_picker()

        MDButtonText:
            text: "Open time picker"
'''


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

    def show_time_picker(self):
        time_picker = MDTimePickerDialVertical()
        time_picker.open()


Example().run()
MDTimePickerDialHorizontal#

The clock dial interface adapts to a device’s orientation. In landscape mode, the stacked input and selection options are positioned side-by-side.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/horizontal-time-picker-preview.gif
def show_time_picker(self):
    MDTimePickerDialHorizontal().open()

Note

You must control the orientation of the time picker yourself.

from typing import Literal

from kivy.clock import Clock
from kivy.lang import Builder
from kivy.properties import ObjectProperty

from kivymd.app import MDApp
from kivymd.theming import ThemeManager
from kivymd.uix.pickers import (
    MDTimePickerDialHorizontal,
    MDTimePickerDialVertical,
)

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release:
            app.open_time_picker_horizontal("1", "10")                 if self.theme_cls.device_orientation == "landscape" else                 app.open_time_picker_vertical("1", "10")

        MDButtonText:
            text: "Open time picker"
'''


class Example(MDApp):
    ORIENTATION = Literal["portrait", "landscape"]
    time_picker_horizontal: MDTimePickerDialHorizontal = ObjectProperty(
        allownone=True
    )
    time_picker_vertical: MDTimePickerDialHorizontal = ObjectProperty(
        allownone=True
    )

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

    def check_orientation(
        self, instance: ThemeManager, orientation: ORIENTATION
    ):
        if orientation == "portrait" and self.time_picker_horizontal:
            self.time_picker_horizontal.dismiss()
            hour = str(self.time_picker_horizontal.time.hour)
            minute = str(self.time_picker_horizontal.time.minute)
            Clock.schedule_once(
                lambda x: self.open_time_picker_vertical(hour, minute),
                0.1,
            )
        elif orientation == "landscape" and self.time_picker_vertical:
            self.time_picker_vertical.dismiss()
            hour = str(self.time_picker_vertical.time.hour)
            minute = str(self.time_picker_vertical.time.minute)
            Clock.schedule_once(
                lambda x: self.open_time_picker_horizontal(hour, minute),
                0.1,
            )

    def open_time_picker_horizontal(self, hour, minute):
        self.time_picker_vertical = None
        self.time_picker_horizontal = MDTimePickerDialHorizontal(
            hour=hour, minute=minute
        )
        self.time_picker_horizontal.open()

    def open_time_picker_vertical(self, hour, minute):
        self.time_picker_horizontal = None
        self.time_picker_vertical = MDTimePickerDialVertical(
            hour=hour, minute=minute
        )
        self.time_picker_vertical.open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-control-orientation.gif
MDTimePickerInput#

Time input pickers allow people to specify a time using keyboard numbers. This input option should be accessible from any other mobile time picker interface by tapping the keyboard icon.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/input-time-picker-preview.gif
def show_time_picker(self):
    MDTimePickerInput().open()
Events#
on_edit event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-edit.gif
from kivy.clock import Clock
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.pickers import MDTimePickerDialVertical, MDTimePickerInput

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_time_picker_vertical()

        MDButtonText:
            text: "Open time picker"
'''


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

    def on_edit_time_picker_input(self, time_picker_input):
        time_picker_input.dismiss()
        Clock.schedule_once(self.show_time_picker_vertical, 0.2)

    def show_time_picker_input(self, *args):
        time_picker_input = MDTimePickerInput()
        time_picker_input.bind(on_edit=self.on_edit_time_picker_input)
        time_picker_input.open()

    def on_edit_time_picker_vertical(self, time_picker_vertical):
        time_picker_vertical.dismiss()
        Clock.schedule_once(self.show_time_picker_input, 0.2)

    def show_time_picker_vertical(self, *args):
        time_picker_vertical = MDTimePickerDialVertical()
        time_picker_vertical.bind(on_edit=self.on_edit_time_picker_vertical)
        time_picker_vertical.open()


Example().run()
on_hour_select event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-hour-select.gif
def on_hour_select(
    self, time_picker_vertical: MDTimePickerDialVertical, mode: str
):
    MDSnackbar(
        MDSnackbarSupportingText(
            text=f"On '{mode}' select",
        ),
        y=dp(24),
        orientation="horizontal",
        pos_hint={"center_x": 0.5},
        size_hint_x=0.5,
    ).open()

def show_time_picker_vertical(self, *args):
    time_picker_vertical = MDTimePickerDialVertical()
    time_picker_vertical.bind(on_hour_select=self.on_hour_select)
    time_picker_vertical.open()
on_minute_select event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-minute-select.gif
def on_minute_select(
    self, time_picker_vertical: MDTimePickerDialVertical, mode: str
):
    MDSnackbar(
        MDSnackbarSupportingText(
            text=f"On '{mode}' select",
        ),
        y=dp(24),
        orientation="horizontal",
        pos_hint={"center_x": 0.5},
        size_hint_x=0.5,
    ).open()

def show_time_picker_vertical(self, *args):
    time_picker_vertical = MDTimePickerDialVertical()
    time_picker_vertical.bind(on_minute_select=self.on_minute_select)
    time_picker_vertical.open()
on_am_pm event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-am-pm.gif
def on_am_pm(
    self, time_picker_vertical: MDTimePickerDialVertical, am_pm: str
):
    MDSnackbar(
        MDSnackbarSupportingText(
            text=f"'{am_pm.upper()}' select",
        ),
        y=dp(24),
        orientation="horizontal",
        pos_hint={"center_x": 0.5},
        size_hint_x=0.5,
    ).open()

def show_time_picker_vertical(self, *args):
    time_picker_vertical = MDTimePickerDialVertical()
    time_picker_vertical.bind(on_am_pm=self.on_am_pm)
    time_picker_vertical.open()
on_selector_hour event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-selector-hour.gif
def on_selector_hour(
    self, time_picker_vertical: MDTimePickerDialVertical, hour: str
):
    MDSnackbar(
        MDSnackbarSupportingText(
            text=f"The value of the hour is `{hour}` select",
        ),
        y=dp(24),
        orientation="horizontal",
        pos_hint={"center_x": 0.5},
        size_hint_x=0.5,
    ).open()

def show_time_picker_vertical(self, *args):
    time_picker_vertical = MDTimePickerDialVertical()
    time_picker_vertical.bind(on_selector_hour=self.on_selector_hour)
    time_picker_vertical.open()
on_selector_minute event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-selector-minute.gif
def on_selector_minute(
    self, time_picker_vertical: MDTimePickerDialVertical, minute: str
):
    MDSnackbar(
        MDSnackbarSupportingText(
            text=f"The value of the hour is `{minute}` select",
        ),
        y=dp(24),
        orientation="horizontal",
        pos_hint={"center_x": 0.5},
        size_hint_x=0.5,
    ).open()

def show_time_picker_vertical(self, *args):
    time_picker_vertical = MDTimePickerDialVertical()
    time_picker_vertical.bind(on_selector_minute=self.on_selector_minute)
    time_picker_vertical.open()
on_cancel event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-cancel.gif
def on_cancel(
    self, time_picker_vertical: MDTimePickerDialVertical
):
    time_picker_vertical.dismiss()

def show_time_picker_vertical(self, *args):
    time_picker_vertical = MDTimePickerDialVertical()
    time_picker_vertical.bind(on_cancel=self.on_cancel)
    time_picker_vertical.open()
on_ok event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-ok.gif
def on_ok(
    self, time_picker_vertical: MDTimePickerDialVertical
):
    MDSnackbar(
        MDSnackbarSupportingText(
            text=f"Time is `{time_picker_vertical.time}`",
        ),
        y=dp(24),
        orientation="horizontal",
        pos_hint={"center_x": 0.5},
        size_hint_x=0.5,
    ).open()

def show_time_picker_vertical(self, *args):
    time_picker_vertical = MDTimePickerDialVertical()
    time_picker_vertical.bind(on_ok=self.on_ok)
    time_picker_vertical.open()
on_time_input event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-input-event-on-time-input.gif
def on_time_input(
    self,
    time_picker_vertical: MDTimePickerInput,
    type_time: str,
    value: str,
):
    MDSnackbar(
        MDSnackbarSupportingText(
            text=f"The {type_time} value is set to {value}",
        ),
        y=dp(24),
        orientation="horizontal",
        pos_hint={"center_x": 0.5},
        size_hint_x=0.5,
    ).open()

def show_time_picker_vertical(self, *args):
    time_picker_vertical = MDTimePickerInput()
    time_picker_vertical.bind(on_time_input=self.on_time_input)
    time_picker_vertical.open()
API break#
1.2.0 version#
time_picker_dialog = MDTimePicker()
time_picker_dialog.open()
2.0.0 version#
# time_picker_dialog = MDTimePickerDialVertical()
# time_picker_dialog = MDTimePickerDialHorizontal()

time_picker_dialog = MDTimePickerInput()
time_picker_dialog.open()
API - kivymd.uix.pickers.timepicker.timepicker#
class kivymd.uix.pickers.timepicker.timepicker.MDBaseTimePicker(**kwargs)#

Implements the base class of the time picker.

New in version 2.0.0.

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

Events:
on_cancel

Fired when the ‘Cancel’ button is pressed.

on_ok

Fired when the ‘Ok’ button is pressed.

on_dismiss

Fired when a date picker closes.

on_edit

Fired when you click on the date editing icon.

on_hour_select

Fired when the hour input field container is clicked.

on_minute_select

Fired when the minute input field container is clicked.

on_am_pm

Fired when the AP/PM switching elements are pressed.

on_selector_hour

Fired when switching the hour value in the clock face container.

on_selector_minute

Fired when switching the minute value in the clock face container.

hour#

Current hour.

hour is an StringProperty and defaults to ‘12’.

minute#

Current minute.

minute is an StringProperty and defaults to 0.

am_pm#

Current AM/PM mode.

am_pm is an OptionProperty and defaults to ‘am’.

animation_duration#

Duration of the animations.

animation_duration is an NumericProperty and defaults to 0.2.

animation_transition#

Transition type of the animations.

animation_transition is an StringProperty and defaults to ‘out_quad’.

time#

Returns the current time object.

time is an ObjectProperty and defaults to None.

headline_text#

Headline text.

headline_text is an StringProperty and defaults to ‘Select time’.

text_button_ok#

The text of the confirmation button.

text_button_ok is a StringProperty and defaults to ‘Ok’.

text_button_cancel#

The text of the cancel button.

text_button_cancel is a StringProperty and defaults to ‘Cancel’.

radius#

Container radius.

radius is an VariableListProperty and defaults to [dp(16), dp(16), dp(16), dp(16)].

is_open#

Is the date picker dialog open.

is_open is a BooleanProperty and defaults to False.

scrim_color#

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

scrim_color is a ColorProperty and defaults to [0, 0, 0, 0.5].

set_time(time_obj: datetime.time) None#

Manually set time dialog with the specified time.

open() None#

Show the dialog time picker.

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

dismiss(*args) None#

Dismiss the dialog time picker.

on_dismiss(*args) None#

Fired when a time picker closes.

on_cancel(*args) None#

Fired when the ‘Cancel’ button is pressed.

on_ok(*args) None#

Fired when the ‘Ok’ button is pressed.

on_hour_select(*args) None#

Fired when the hour input field container is clicked.

on_minute_select(*args) None#

Fired when the minute input field container is clicked.

on_am_pm(*args) None#

Fired when the AP/PM switching elements are pressed.

on_edit(*args) None#

Fired when you click on the time editing icon.

on_selector_hour(*args) None#

Fired when switching the hour value in the clock face container.

on_selector_minute(*args) None#

Fired when switching the minute value in the clock face container.

on_time_input(*args) None#

Fired when switching the minute value in the clock face container.

class kivymd.uix.pickers.timepicker.timepicker.MDTimePickerInput(**kwargs)#

Implements input time picker.

New in version 2.0.0.

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

class kivymd.uix.pickers.timepicker.timepicker.MDTimePickerDialVertical(**kwargs)#

Implements vertical time picker.

New in version 2.0.0.

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

class kivymd.uix.pickers.timepicker.timepicker.MDTimePickerDialHorizontal(**kwargs)#

Implements horizontal time picker.

New in version 2.0.0.

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

DatePicker#

#

Date pickers let people select a date, or a range of dates.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/date-picker.png
  • Date pickers can display past, present, or future dates

  • Three types: docked, modal, modal input

  • Clearly indicate important dates, such as current and selected days

  • Follow common patterns, like a calendar view

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/date-picker-types.png
  1. Docked date picker

  2. Modal date picker

  3. Modal date input

KivyMD provides the following date pickers classes for use:

MDDockedDatePicker#

Docked datepickers allow the selection of a specific date and year. The docked datepicker displays a date input field by default, and a dropdown calendar appears when the user taps on the input field. Either form of date entry can be interacted with.

Docked date pickers are ideal for navigating dates in both the near future or past and the distant future or past, as they provide multiple ways to select dates.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/docked-data-picker-preview.gif
from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.pickers import MDDockedDatePicker

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

    MDTextField:
        id: field
        mode: "outlined"
        pos_hint: {'center_x': .5, 'center_y': .85}
        size_hint_x: .5
        on_focus: app.show_date_picker(self.focus)

        MDTextFieldHintText:
            text: "Docked date picker"

        MDTextFieldHelperText:
            text: "MM/DD/YYYY"
            mode: "persistent"

        MDTextFieldTrailingIcon:
            icon: "calendar"
'''


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

    def show_date_picker(self, focus):
        if not focus:
            return

        date_dialog = MDDockedDatePicker()
        # You have to control the position of the date picker dialog yourself.
        date_dialog.pos = [
            self.root.ids.field.center_x - date_dialog.width / 2,
            self.root.ids.field.y - (date_dialog.height + dp(32)),
        ]
        date_dialog.open()


Example().run()
MDModalDatePicker#

Modal date pickers navigate across dates in several ways:

  • To navigate across months, swipe horizontally (not implemented in KivyMD)

  • To navigate across years, scroll vertically (not implemented in KivyMD)

  • To access the year picker, tap the year

Don’t use a modal date picker to prompt for dates in the distant past or future, such as a date of birth. In these cases, use a modal input picker or a docked datepicker instead.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-preview.gif
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalDatePicker

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


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

    def show_date_picker(self):
        date_dialog = MDModalDatePicker()
        date_dialog.open()


Example().run()
MDModalInputDatePicker#

Modal date inputs allow the manual entry of dates using the numbers on a keyboard. Users can input a date or a range of dates in a dialog.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-input-data-picker-preview.gif
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalInputDatePicker

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


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

    def show_date_picker(self):
        date_dialog = MDModalInputDatePicker()
        date_dialog.open()


Example().run()
The range of available dates#

To display only the selected date range, use the min_date and max_date parameters:

def show_modal_date_picker(self, *args):
    MDModalDatePicker(
        mark_today=False,
        min_date=datetime.date.today(),
        max_date=datetime.date(
            datetime.date.today().year,
            datetime.date.today().month,
            datetime.date.today().day + 4,
        ),
    ).open()

Only dates in the specified range will be available for selection:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-min-max-date.gif
Select the date range#

To select the date range, use the mode parameter with the value “range”:

def show_modal_date_picker(self, *args):
    MDModalDatePicker(mode="range").open()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-range.gif
Setting the date range manually#
def show_modal_date_picker(self, *args):
    MDModalInputDatePicker(mode="range").open()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-input-data-picker-range.gif
Events#
on_edit event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-event-on-edit.gif
from kivy.clock import Clock
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalInputDatePicker, MDModalDatePicker

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_modal_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


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

    def show_modal_input_date_picker(self, *args):
        def on_edit(*args):
            date_dialog.dismiss()
            Clock.schedule_once(self.show_modal_date_picker, 0.2)

        date_dialog = MDModalInputDatePicker()
        date_dialog.bind(on_edit=on_edit)
        date_dialog.open()

    def on_edit(self, instance_date_picker):
        instance_date_picker.dismiss()
        Clock.schedule_once(self.show_modal_input_date_picker, 0.2)

    def show_modal_date_picker(self, *args):
        date_dialog = MDModalDatePicker()
        date_dialog.bind(on_edit=self.on_edit)
        date_dialog.open()


Example().run()
on_select_day event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-event-on-select-day.gif
from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalDatePicker
from kivymd.uix.snackbar import MDSnackbar, MDSnackbarSupportingText

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_modal_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


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

    def on_select_day(self, instance_date_picker, number_day):
        instance_date_picker.dismiss()
        MDSnackbar(
            MDSnackbarSupportingText(
                text=f"The selected day is {number_day}",
            ),
            y=dp(24),
            orientation="horizontal",
            pos_hint={"center_x": 0.5},
            size_hint_x=0.5,
            background_color="olive"
        ).open()

    def show_modal_date_picker(self, *args):
        date_dialog = MDModalDatePicker()
        date_dialog.bind(on_select_day=self.on_select_day)
        date_dialog.open()


Example().run()
on_select_month event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-event-on-select-month.gif
def on_select_month(self, instance_date_picker, number_month):
    [...]

def show_modal_date_picker(self, *args):
    [...]
    date_dialog.bind(on_select_month=self.on_select_month)
    [...]
on_select_year event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-event-on-select-year.gif
def on_select_year(self, instance_date_picker, number_year):
    [...]

def show_modal_date_picker(self, *args):
    [...]
    date_dialog.bind(on_select_month=self.on_select_year)
    [...]
on_cancel event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-event-on-cancel.gif
def on_cancel(self, instance_date_picker):
    [...]

def show_modal_date_picker(self, *args):
    [...]
    date_dialog.bind(on_cancel=self.on_cancel)
    [...]
on_ok event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-event-on-ok.gif
def on_ok(self, instance_date_picker):
    print(instance_date_picker.get_date()[0])

def show_modal_date_picker(self, *args):
    [...]
    date_dialog.bind(on_ok=self.on_ok)
    [...]
on_ok with range event#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/modal-data-picker-event-on-ok-with-range.gif
import datetime

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalDatePicker
from kivymd.uix.snackbar import (
    MDSnackbar, MDSnackbarSupportingText, MDSnackbarText
)

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_modal_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


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

    def on_ok(self, instance_date_picker):
        MDSnackbar(
            MDSnackbarText(
                text="Selected dates is:",
            ),
            MDSnackbarSupportingText(
                text="\n".join(str(date) for date in instance_date_picker.get_date()),
                padding=[0, 0, 0, dp(12)],
            ),
            y=dp(124),
            pos_hint={"center_x": 0.5},
            size_hint_x=0.5,
            padding=[0, 0, "8dp", "8dp"],
        ).open()

    def show_modal_date_picker(self, *args):
        date_dialog = MDModalDatePicker(
            mode="range",
            min_date=datetime.date.today(),
            max_date=datetime.date(
                datetime.date.today().year,
                datetime.date.today().month,
                datetime.date.today().day + 4,
            ),
        )
        date_dialog.bind(on_ok=self.on_ok)
        date_dialog.open()


Example().run()
API break#
1.2.0 version#
date_dialog = MDDatePicker()
date_dialog.open()
2.0.0 version#
# date_dialog = MDModalDatePicker()
# date_dialog = MDModalInputDatePicker()

date_dialog = MDDockedDatePicker()
date_dialog.open()
API - kivymd.uix.pickers.datepicker.datepicker#
class kivymd.uix.pickers.datepicker.datepicker.MDBaseDatePicker(year=None, month=None, day=None, firstweekday=0, **kwargs)#

Implements the base class of the date picker.

New in version 2.0.0.

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

Events:
on_select_day

Fired when a day is selected.

on_select_month

Fired when a month is selected.

on_select_year

Fired when a year is selected.

on_cancel

Fired when the ‘Cancel’ button is pressed.

on_ok

Fired when the ‘Ok’ button is pressed.

on_edit

Fired when you click on the date editing icon.

on_dismiss

Fired when a date picker closes.

day#

The day of the month to be opened by default. If not specified, the current number will be used.

day is an NumericProperty and defaults to 0.

month#

The number of month to be opened by default. If not specified, the current number will be used.

month is an NumericProperty and defaults to 0.

year#

The year of month to be opened by default. If not specified, the current number will be used.

year is an NumericProperty and defaults to 0.

min_year#

The year of month to be opened by default. If not specified, the current number will be used.

min_year is an NumericProperty and defaults to 1914.

max_year#

The year of month to be opened by default. If not specified, the current number will be used.

max_year is an NumericProperty and defaults to 2121.

mode#

Dialog type. Available options are: ‘picker’, ‘range’.

mode is an OptionProperty and defaults to picker.

min_date#

The minimum value of the date range for the ‘mode’ parameter. Must be an object <class ‘datetime.date’>.

min_date is an ObjectProperty and defaults to None.

max_date#

The minimum value of the date range for the ‘mode’ parameter. Must be an object <class ‘datetime.date’>.

max_date is an ObjectProperty and defaults to None.

radius#

Container radius.

radius is an VariableListProperty and defaults to [dp(16), dp(16), dp(16), dp(16)].

scrim_color#

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

scrim_color is a ColorProperty and defaults to [0, 0, 0, 0.5].

supporting_text#

Supporting text.

supporting_text is a StringProperty and defaults to ‘Select date’.

text_button_ok#

The text of the confirmation button.

text_button_ok is a StringProperty and defaults to ‘Ok’.

text_button_cancel#

The text of the cancel button.

text_button_cancel is a StringProperty and defaults to ‘Cancel’.

mark_today#

Highlights the current day.

mark_today is a BooleanProperty and defaults to True.

is_open#

Is the date picker dialog open.

is_open is a BooleanProperty and defaults to False.

sel_year#
sel_month#
sel_day#
calendar_layout#
get_date(*args) list#

Returns a list of dates in the format [datetime.date(yyyy, mm, dd), …]. The list has two dates if you use a date interval.

set_text_full_date() str#

Returns a string like “Tue, Feb 2”.

compare_date_range() None#
change_month(operation: str) None#

Called when “chevron-left” and “chevron-right” buttons are pressed. Switches the calendar to the previous/next month.

generate_list_widgets_days() None#
update_calendar(year, month) None#
set_selected_widget(widget) None#
restore_calendar_layout_properties() None#
set_calendar_layout_properties(method) None#
dismiss(*args) None#

Dismiss the dialog date picker.

open() None#

Show the dialog date picker.

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_select_day(*args) None#

Fired when a day is selected.

on_select_month(*args) None#

Fired when a month is selected.

on_select_year(*args) None#

Fired when a year is selected.

on_cancel(*args) None#

Fired when the ‘Cancel’ button is pressed.

on_ok(*args) None#

Fired when the ‘Ok’ button is pressed.

on_edit(*args) None#

Fired when you click on the date editing icon.

on_dismiss(*args) None#

Fired when a date picker closes.

class kivymd.uix.pickers.datepicker.datepicker.MDDockedDatePicker(**kwargs)#

Implements docked date picker.

New in version 2.0.0.

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

generate_menu_month_year_selection(menu_type: str = 'month') None#

Generates a list for the month or year selection menu.

open_close_menu_month_year_selection(state: bool = True, menu_type: str = 'month') None#

Hides the calendar layout and opens the list to select the month or year.

class kivymd.uix.pickers.datepicker.datepicker.MDModalDatePicker(**kwargs)#

Implements modal date picker.

New in version 2.0.0.

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

open() None#

Show the dialog date picker.

generate_list_widgets_years() None#
open_menu_year_selection(*args) None#
class kivymd.uix.pickers.datepicker.datepicker.MDModalInputDatePicker(*args, **kwargs)#

Implements modal input date picker.

New in version 2.0.0.

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

date_format#

Format of date strings that will be entered. Available options are: ‘dd/mm/yyyy’, ‘mm/dd/yyyy’, ‘yyyy/mm/dd’.

date_format is an OptionProperty and defaults to None.

default_input_date#

If true, the current date will be set in the input field.

default_input_date is a BooleanProperty and defaults to True.

error_text#

Error text when the date entered by the user is not valid.

error_text is a StringProperty and defaults to ‘Invalid date format’.

supporting_input_text#

Auxiliary text when entering the date manually.

supporting_input_text is a StringProperty and defaults to ‘Enter date’.

generate_list_widgets_days() None#
update_calendar(*args) None#
set_input_date(input_date: str) None#
get_date(*args) list#

Returns a list of dates in the format [datetime.date(yyyy, mm, dd), …]. The list has two dates if you use a date interval.

get_current_date_from_format() str#

Returns the date according to the set format in date_format.

open() None#

Show the dialog date picker.

Divider#

#

New in version 2.0.0.

Dividers are thin lines that group content in lists or other containers.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/divider.png
  • Make dividers visible but not bold

  • Only use dividers if items can’t be grouped with open space

  • Use dividers to group things, not separate individual items

KivyMD provides the following bar positions for use:

HorizontalDivider#

Dividers are one way to visually group components and create hierarchy. They can also be used to imply nested parent/child relationships.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/divider-horizontal-desc.png
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDDivider:
        size_hint_x: .5
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/divider-horizontal.png
VerticalDivider#

A vertical divider can be used to arrange content on a larger screen, such as separating paragraph text from video or imagery media.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/divider-vertical-desc.png
MDDivider:
    size_hint_y: .5
    orientation: "vertical"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/divider-vertical.png
API break#
1.2.0 version#
MDSeparator:
    [...]
2.0.0 version#
MDDivider:
    [...]
API - kivymd.uix.divider.divider#
class kivymd.uix.divider.divider.MDDivider(**kwargs)#

A divider line.

New in version 2.0.0.

For more information, see in the BoxLayout class documentation.

color#

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

color is a ColorProperty and defaults to None.

divider_width#

Divider width.

divider_width is an NumericProperty and defaults to dp(1).

on_orientation(*args) None#

Fired when the values of orientation change.

ImageList#

#

Image lists display a collection of images in an organized grid.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/image-list.png
Usage#
MDSmartTile:
    [...]

    MDSmartTileImage:
        [...]

    MDSmartTileOverlayContainer:
        [...]

        # Content
        [...]
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/image-list-anatomy.png
Example#
from kivy.lang import Builder

from kivymd.app import MDApp

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

    MDSmartTile:
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint: None, None
        size: "320dp", "320dp"
        overlap: False

        MDSmartTileImage:
            source: "bg.jpg"
            radius: [dp(24), dp(24), 0, 0]

        MDSmartTileOverlayContainer:
            md_bg_color: 0, 0, 0, .5
            adaptive_height: True
            padding: "8dp"
            spacing: "8dp"
            radius: [0, 0, dp(24), dp(24)]

            MDIconButton:
                icon: "heart-outline"
                theme_icon_color: "Custom"
                icon_color: 1, 0, 0, 1
                pos_hint: {"center_y": .5}
                on_release:
                    self.icon = "heart" \
                    if self.icon == "heart-outline" else \
                    "heart-outline"

            MDLabel:
                text: "Ibanez GRG121DX-BKF"
                theme_text_color: "Custom"
                text_color: "white"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/image-list-example.png
API break#
1.2.0 version#
MDSmartTile:
    [...]

    # Content.
    MDIconButton:
        [...]

    MDLabel:
        [...]
2.0.0 version#
MDSmartTile:
    [...]

    MDSmartTileImage:
        [...]

    MDSmartTileOverlayContainer:
        [...]

        # Content.
        [...]
API - kivymd.uix.imagelist.imagelist#
class kivymd.uix.imagelist.imagelist.MDSmartTileImage(**kwargs)#

Implements the tile image.

Changed in version 2.0.0: The SmartTileImage class has been renamed to MDSmartTileImage.

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

class kivymd.uix.imagelist.imagelist.MDSmartTileOverlayContainer(*args, **kwargs)#

Implements a container for custom widgets to be added to the tile.

Changed in version 2.0.0: The SmartTileOverlayBox class has been renamed to MDSmartTileOverlayContainer.

For more information, see in the BoxLayout class documentation.

class kivymd.uix.imagelist.imagelist.MDSmartTile(**kwargs)#

A tile for more complex needs.

For more information, see in the MDRelativeLayout class documentation.

Includes an image, a container to place overlays and a box that can act as a header or a footer, as described in the Material Design specs.

Events:
on_press

Fired when the button is pressed.

on_release

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

overlay_mode#

Determines weather the information box acts as a header or footer to the image. Available are options: ‘footer’, ‘header’.

Changed in version 2.0.0: The box_position attribute has been renamed to overlay_mode.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/image-list-overlay-mode.png

overlay_mode is a OptionProperty and defaults to ‘footer’.

overlap#

Determines if the header/footer overlaps on top of the image or not.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/image-list-overlap.png

overlap is a BooleanProperty and defaults to True.

on_release(*args)#

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

on_press(*args)#

Fired when the button is pressed.

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)

Swiper#

#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mdswiper-preview.gif
Usage#
MDSwiper:

    MDSwiperItem:

    MDSwiperItem:

    MDSwiperItem:
Example#
from kivy.lang.builder import Builder

from kivymd.app import MDApp

kv = '''
<MySwiper@MDSwiperItem>

    FitImage:
        source: "bg.jpg"
        radius: [dp(20),]


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDSwiper:
        size_hint_y: None
        height: root.height - dp(40)
        y: root.height - self.height - dp(20)

        MySwiper:

        MySwiper:

        MySwiper:

        MySwiper:

        MySwiper:
'''


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


Main().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/swiper-example.gif

Warning

The width of MDSwiperItem is adjusted automatically. Consider changing that by width_mult.

Warning

The width of MDSwiper is automatically adjusted according to the width of the window.

MDSwiper provides the following events for use:

__events__ = (
    "on_swipe",
    "on_pre_swipe",
    "on_overswipe_right",
    "on_overswipe_left",
    "on_swipe_left",
    "on_swipe_right"
)
MDSwiper:
    on_swipe: print("on_swipe")
    on_pre_swipe: print("on_pre_swipe")
    on_overswipe_right: print("on_overswipe_right")
    on_overswipe_left: print("on_overswipe_left")
    on_swipe_left: print("on_swipe_left")
    on_swipe_right: print("on_swipe_right")
API - kivymd.uix.swiper.swiper#
class kivymd.uix.swiper.swiper.MDSwiperItem(*args, **kwargs)#

Swiper item class.

For more information, see in the MDBoxLayout class documentation.

class kivymd.uix.swiper.swiper.MDSwiper(*args, **kwargs)#

Swiper class.

For more information, see in the MDScrollView class documentation.

items_spacing#

The space between each MDSwiperItem.

items_spacing is an NumericProperty and defaults to 20dp.

transition_duration#

Duration of switching between MDSwiperItem.

transition_duration is an NumericProperty and defaults to 0.2.

size_duration#

Duration of changing the size of MDSwiperItem.

transition_duration is an NumericProperty and defaults to 0.2.

size_transition#

The type of animation used for changing the size of MDSwiperItem.

size_transition is an StringProperty and defaults to out_quad.

swipe_transition#

The type of animation used for swiping.

swipe_transition is an StringProperty and defaults to out_quad.

swipe_distance#

Distance to move before swiping the MDSwiperItem.

swipe_distance is an NumericProperty and defaults to 70dp.

width_mult#

This number is multiplied by items_spacing x2 and then subtracted from the width of window to specify the width of MDSwiperItem. So by decreasing the width_mult the width of MDSwiperItem increases and vice versa.

width_mult is an NumericProperty and defaults to 3.

swipe_on_scroll#

Wheter to swipe on mouse wheel scrolling or not.

swipe_on_scroll is an BooleanProperty and defaults to True.

add_widget(widget, index=0)#

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(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)
set_current(index)#

Switch to given MDSwiperItem index.

get_current_index()#

Returns the current MDSwiperItem index.

get_current_item()#

Returns the current MDSwiperItem instance.

get_items()#

Returns the list of MDSwiperItem children.

Note

Use get_items() to get the list of children instead of MDSwiper.children.

on_swipe()#
on_pre_swipe()#
on_overswipe_right()#
on_overswipe_left()#
on_swipe_left()#
on_swipe_right()#
swipe_left()#
swipe_right()#
on_scroll_start(touch, check_children=True)#
on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_up(touch)#

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

RefreshLayout#

#
Example#
from kivy.clock import Clock
from kivy.lang import Builder
from kivy.factory import Factory
from kivy.properties import StringProperty

from kivymd.app import MDApp
from kivymd.uix.button import MDIconButton
from kivymd.icon_definitions import md_icons
from kivymd.uix.list import ILeftBodyTouch, OneLineIconListItem
from kivymd.theming import ThemeManager
from kivymd.utils import asynckivy

Builder.load_string('''
<ItemForList>
    text: root.text

    IconLeftSampleWidget:
        icon: root.icon


<Example@MDFloatLayout>

    MDBoxLayout:
        orientation: 'vertical'

        MDTopAppBar:
            title: app.title
            md_bg_color: app.theme_cls.primary_color
            background_palette: 'Primary'
            elevation: 4
            left_action_items: [['menu', lambda x: x]]

        MDScrollViewRefreshLayout:
            id: refresh_layout
            refresh_callback: app.refresh_callback
            root_layout: root
            spinner_color: "brown"
            circle_color: "white"

            MDGridLayout:
                id: box
                adaptive_height: True
                cols: 1
''')


class IconLeftSampleWidget(ILeftBodyTouch, MDIconButton):
    pass


class ItemForList(OneLineIconListItem):
    icon = StringProperty()


class Example(MDApp):
    title = 'Example Refresh Layout'
    screen = None
    x = 0
    y = 15

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        self.screen = Factory.Example()
        self.set_list()

        return self.screen

    def set_list(self):
        async def set_list():
            names_icons_list = list(md_icons.keys())[self.x:self.y]
            for name_icon in names_icons_list:
                await asynckivy.sleep(0)
                self.screen.ids.box.add_widget(
                    ItemForList(icon=name_icon, text=name_icon))
        asynckivy.start(set_list())

    def refresh_callback(self, *args):
        '''
        A method that updates the state of your application
        while the spinner remains on the screen.
        '''

        def refresh_callback(interval):
            self.screen.ids.box.clear_widgets()
            if self.x == 0:
                self.x, self.y = 15, 30
            else:
                self.x, self.y = 0, 15
            self.set_list()
            self.screen.ids.refresh_layout.refresh_done()
            self.tick = 0

        Clock.schedule_once(refresh_callback, 1)


Example().run()
API - kivymd.uix.refreshlayout.refreshlayout#
class kivymd.uix.refreshlayout.refreshlayout.MDScrollViewRefreshLayout(*args, **kwargs)#

Refresh layout class.

For more information, see in the ThemableBehavior and MDScrollView class documentation.

root_layout#

The spinner will be attached to this layout.

root_layout is a ObjectProperty and defaults to None.

refresh_callback#

The method that will be called at the on_touch_up event, provided that the overscroll of the list has been registered.

refresh_callback is a ObjectProperty and defaults to None.

spinner_color#

Color of the spinner in (r, g, b, a) or string format.

New in version 1.2.0.

spinner_color is a ColorProperty and defaults to [1, 1, 1, 1].

circle_color#

Color of the ellipse around the spinner in (r, g, b, a) or string format.

New in version 1.2.0.

circle_color is a ColorProperty and defaults to None.

show_transition#

Transition of the spinner’s opening.

New in version 1.2.0.

show_transition is a StringProperty and defaults to ‘out_elastic’.

show_duration#

Duration of the spinner display.

New in version 1.2.0.

show_duration is a NumericProperty and defaults to 0.8.

hide_transition#

Transition of hiding the spinner.

New in version 1.2.0.

hide_transition is a StringProperty and defaults to ‘out_elastic’.

hide_duration#

Duration of hiding the spinner.

New in version 1.2.0.

hide_duration is a NumericProperty and defaults to 0.8.

on_touch_up(*args)#

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

refresh_done() None#

Tooltip#

#

Tooltips display brief labels or messages.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-preview.png
  • Use tooltips to add additional context to a button or other UI element

  • Two types: plain and rich

  • Use plain tooltips to describe elements or actions of icon buttons

  • Use rich tooltips to provide more details, like describing the value of a feature

  • Rich tooltips can include an optional title, link, and buttons

KivyMD provides two types of tooltip:

  1. Plain tooltip

  2. Rich tooltip

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-type.png
Usage of tooltip plain#
from kivy.lang import Builder
from kivy.properties import StringProperty

from kivymd.uix.button import MDButton
from kivymd.uix.tooltip import MDTooltip
from kivymd.app import MDApp

KV = '''
<YourTooltipClass>

    MDTooltipPlain:
        text:
            "Grant value is calculated using the closing stock price \\n" \
            "from the day before the grant date. Amounts do not \\n" \
            "reflect tax witholdings."


<TooltipMDIconButton>

    MDButtonText:
        text: root.text


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    TooltipMDIconButton:
        text: "Tooltip button"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class YourTooltipClass(MDTooltip):
    '''Implements your tooltip base class.'''


class TooltipMDIconButton(YourTooltipClass, MDButton):
    '''Implements a button with tooltip behavior.'''

    text = StringProperty()


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-plain-usage.gif
The anatomy of a plain tooltip#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-plain-anatomy.png
Usage of tooltip rich#
from kivy.lang import Builder
from kivy.properties import StringProperty

from kivymd.uix.button import MDButton
from kivymd.uix.tooltip import MDTooltip
from kivymd.app import MDApp

KV = '''
<YourTooltipClass>

    MDTooltipRich:
        id: tooltip
        auto_dismiss: False

        MDTooltipRichSubhead:
            text: "Add others"

        MDTooltipRichSupportingText:
            text:
                "Grant value is calculated using the closing stock price \\n" \
                "from the day before the grant date. Amounts do not \\n" \
                "reflect tax witholdings."

        MDTooltipRichActionButton:
            on_press: tooltip.dismiss()

            MDButtonText:
                text: "Learn more"


<TooltipMDIconButton>

    MDButtonText:
        text: root.text


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    TooltipMDIconButton:
        text: "Tooltip button"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class YourTooltipClass(MDTooltip):
    '''Implements your tooltip base class.'''


class TooltipMDIconButton(YourTooltipClass, MDButton):
    '''Implements a button with tooltip behavior.'''

    text = StringProperty()


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-rich-usage.gif
The anatomy of a plain tooltip#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tooltip-m3-rich-anatomy.png
API - kivymd.uix.tooltip.tooltip#
class kivymd.uix.tooltip.tooltip.MDTooltip(**kwargs)#

Tooltip class.

For more information, see in the TouchBehavior class documentation.

Events:
on_open:

Fired when the tooltip opens.

on_dismiss:

Fired when the tooltip is closed.

tooltip_display_delay#

Tooltip display delay.

Note

This property only works on desktop.

tooltip_display_delay is an BoundedNumericProperty and defaults to 0, min of 0 & max of 4.

shift_y#

Y-offset of tooltip to the top.

shift_y is an NumericProperty and defaults to 0.

shift_right#

Shifting the tooltip to the right.

New in version 1.0.0.

shift_right is an NumericProperty and defaults to 0.

shift_left#

Shifting the tooltip to the left.

New in version 1.0.0.

shift_left is an NumericProperty and defaults to 0.

delete_clock(widget, touch, *args)#

Removes a key event from touch.ud.

adjust_tooltip_position() tuple#

Returns the coordinates of the tooltip that fit into the borders of the screen.

display_tooltip(*args) None#

Adds a tooltip widget to the screen and animates its display.

animation_tooltip_show(*args) None#

Animation of opening tooltip on the screen.

animation_tooltip_dismiss(*args) None#

Animation of closing tooltip on the screen.

New in version 1.0.0.

remove_tooltip(*args) None#

Removes the tooltip widget from the screen.

add_widget(widget, *args, **kwargs)#

Add a new widget as a child of this widget.

on_long_touch(touch, *args) None#

Fired when the widget is pressed for a long time.

on_enter(*args) None#

Fired when mouse enter the bbox of the widget.

on_leave(*args) None#

Fired when the mouse goes outside the widget border.

on_open() None#

Default display event handler.

Changed in version 2.0.0: Rename from on_show to on_open.

on_dismiss() None#

Default dismiss event handler.

New in version 1.0.0.

class kivymd.uix.tooltip.tooltip.MDTooltipPlain(*args, **kwargs)#

Tooltip plain class.

New in version 2.0.0.

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

class kivymd.uix.tooltip.tooltip.MDTooltipRichSupportingText(*args, **kwargs)#

Implements supporting text for the MDTooltipRich class.

New in version 2.0.0.

For more information, see in the MDLabel class documentation.

class kivymd.uix.tooltip.tooltip.MDTooltipRichSubhead(*args, **kwargs)#

Implements subhead text for the MDTooltipRich class.

New in version 2.0.0.

For more information, see in the MDLabel class documentation.

class kivymd.uix.tooltip.tooltip.MDTooltipRichActionButton(*args, **kwargs)#

Implements action button for the MDTooltipRich class.

New in version 2.0.0.

For more information, see in the MDButton class documentation.

on_enter() None#

Fired when mouse enter the bbox of the widget.

on_leave() None#

Fired when the mouse goes outside the widget border.

class kivymd.uix.tooltip.tooltip.MDTooltipRich(*args, **kwargs)#

Tooltip rich class.

New in version 2.0.0.

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

auto_dismiss#

This property determines if the view is automatically dismissed when the cursor goes outside of the tooltip body.

auto_dismiss is a BooleanProperty and defaults to True.

on_leave() None#

Fired when the mouse goes outside the widget border.

dismiss() None#

Hides the tooltip.

Chip#

#

Chips can show multiple interactive elements together in the same area, such as a list of selectable movie times, or a series of email contacts. There are four types of chips: assist, filter, input, and suggestion.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/chips.png
Usage#
MDChip:

    MDChipLeadingAvatar:  # MDChipLeadingIcon

    MDChipText:

    MDChipTrailingIcon:
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/chip-anatomy.png
Example#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}

        MDChipText:
            text: "MDChip"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/chip.png
The following types of chips are available:#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/available-type-chips.png
Assist#

Assist chips represent smart or automated actions that can span multiple apps, such as opening a calendar event from the home screen. Assist chips function as though the user asked an assistant to complete the action. They should appear dynamically and contextually in a UI.

An alternative to assist chips are buttons, which should appear persistently and consistently.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/assist-chip.png
Example of assist#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<CommonLabel@MDLabel>
    adaptive_size: True
    theme_text_color: "Custom"
    text_color: "#e6e9df"


<CommonAssistChip@MDChip>
    # Custom attribute.
    text: ""
    icon: ""

    # Chip attribute.
    type: "assist"
    md_bg_color: "#2a3127"
    line_color: "grey"
    elevation: 1
    shadow_softness: 2

    MDChipLeadingIcon:
        icon: root.icon
        theme_text_color: "Custom"
        text_color: "#68896c"

    MDChipText:
        text: root.text
        theme_text_color: "Custom"
        text_color: "#e6e9df"


MDScreen:

    FitImage:
        source: "bg.png"

    MDBoxLayout:
        orientation: "vertical"
        adaptive_size: True
        pos_hint: {"center_y": .6, "center_x": .5}

        CommonLabel:
            text: "in 10 mins"
            bold: True
            pos_hint: {"center_x": .5}

        CommonLabel:
            text: "Therapy with Thea"
            font_style: "H3"
            padding_y: "12dp"

        CommonLabel:
            text: "Video call"
            font_style: "H5"
            pos_hint: {"center_x": .5}

        MDBoxLayout:
            adaptive_size: True
            pos_hint: {"center_x": .5}
            spacing: "12dp"
            padding: 0, "24dp", 0, 0

            CommonAssistChip:
                text: "Home office"
                icon: "map-marker"

            CommonAssistChip:
                text: "Chat"
                icon: "message"

        MDWidget:
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-assist-chip.png
Filter#

Filter chips use tags or descriptive words to filter content. They can be a good alternative to toggle buttons or checkboxes.

Tapping on a filter chip activates it and appends a leading checkmark icon to the starting edge of the chip label.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/filter-chip.png
Example of filtering#
from kivy.lang import Builder
from kivy.properties import StringProperty, ListProperty

from kivymd.app import MDApp
from kivymd.uix.chip import MDChip, MDChipText
from kivymd.uix.list import MDListItem
from kivymd.icon_definitions import md_icons
from kivymd.uix.screen import MDScreen

import asynckivy

Builder.load_string(
    '''
<CustomOneLineIconListItem>

    MDListItemLeadingIcon:
        icon: root.icon

    MDListItemHeadlineText:
        text: root.text


<PreviewIconsScreen>

    MDBoxLayout:
        orientation: "vertical"
        spacing: "14dp"
        padding: "20dp"

        MDTextField:
            id: search_field
            mode: "outlined"
            on_text: root.set_list_md_icons(self.text, True)

            MDTextFieldLeadingIcon:
                icon: "magnify"

            MDTextFieldHintText:
                text: "Search icon"

        MDBoxLayout:
            id: chip_box
            spacing: "12dp"
            adaptive_height: True

        RecycleView:
            id: rv
            viewclass: "CustomOneLineIconListItem"
            key_size: "height"

            RecycleBoxLayout:
                padding: dp(10)
                default_size: None, dp(48)
                default_size_hint: 1, None
                size_hint_y: None
                height: self.minimum_height
                orientation: "vertical"
    '''
)


class CustomOneLineIconListItem(MDListItem):
    icon = StringProperty()
    text = StringProperty()


class PreviewIconsScreen(MDScreen):
    filter = ListProperty()  # list of tags for filtering icons

    def set_filter_chips(self):
        '''Asynchronously creates and adds chips to the container.'''

        async def set_filter_chips():
            for tag in ["Outline", "Off", "On"]:
                await asynckivy.sleep(0)
                chip = MDChip(
                    MDChipText(
                        text=tag,
                    ),
                    type="filter",
                    md_bg_color="#303A29",
                )
                chip.bind(active=lambda x, y, z=tag: self.set_filter(y, z))
                self.ids.chip_box.add_widget(chip)

        asynckivy.start(set_filter_chips())

    def set_filter(self, active: bool, tag: str) -> None:
        '''Sets a list of tags for filtering icons.'''

        if active:
            self.filter.append(tag)
        else:
            self.filter.remove(tag)

    def set_list_md_icons(self, text="", search=False) -> None:
        '''Builds a list of icons.'''

        def add_icon_item(name_icon):
            self.ids.rv.data.append(
                {
                    "icon": name_icon,
                    "text": name_icon,
                }
            )

        self.ids.rv.data = []
        for name_icon in md_icons.keys():
            for tag in self.filter:
                if tag.lower() in name_icon:
                    if search:
                        if text in name_icon:
                            add_icon_item(name_icon)
                    else:
                        add_icon_item(name_icon)


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = PreviewIconsScreen()

    def build(self) -> PreviewIconsScreen:
        self.theme_cls.theme_style = "Dark"
        return self.screen

    def on_start(self) -> None:
        super().on_start()
        self.screen.set_list_md_icons()
        self.screen.set_filter_chips()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-filtering-icons-chip.gif

Tap a chip to select it. Multiple chips can be selected or unselected:

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.chip import MDChip, MDChipText
from kivymd.uix.screen import MDScreen

import asynckivy

Builder.load_string(
    '''
<ChipScreen>

    MDBoxLayout:
        orientation: "vertical"
        spacing: "14dp"
        padding: "20dp"

        MDLabel:
            adaptive_height: True
            text: "Select Type"

        MDStackLayout:
            id: chip_box
            spacing: "12dp"
            adaptive_height: True

        MDWidget:

    MDButton:
        pos: "20dp", "20dp"
        on_release: root.unchecks_chips()

        MDButtonText:
            text: "Uncheck chips"
    '''
)


class ChipScreen(MDScreen):
    async def create_chips(self):
        '''Asynchronously creates and adds chips to the container.'''

        for tag in ["Extra Soft", "Soft", "Medium", "Hard"]:
            await asynckivy.sleep(0)
            self.ids.chip_box.add_widget(
                MDChip(
                    MDChipText(
                        text=tag,
                    ),
                    type="filter",
                    md_bg_color="#303A29",
                    active=True,
                )
            )

    def unchecks_chips(self) -> None:
        '''Removes marks from all chips.'''

        for chip in self.ids.chip_box.children:
            if chip.active:
                chip.active = False


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = ChipScreen()

    def build(self) -> ChipScreen:
        self.theme_cls.theme_style = "Dark"
        return self.screen

    def on_start(self) -> None:
        super().on_start()
        asynckivy.start(self.screen.create_chips())


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-filtering-icons-chip-2.gif

Alternatively, a single chip can be selected. This offers an alternative to toggle buttons, radio buttons, or single select menus:

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.chip import MDChip, MDChipText
from kivymd.uix.screen import MDScreen

import asynckivy

Builder.load_string(
    '''
<ChipScreen>

    MDBoxLayout:
        orientation: "vertical"
        spacing: "14dp"
        padding: "20dp"

        MDLabel:
            adaptive_height: True
            text: "Select Type"

        MDStackLayout:
            id: chip_box
            spacing: "12dp"
            adaptive_height: True

        MDWidget:
    '''
)


class ChipScreen(MDScreen):
    async def create_chips(self):
        '''Asynchronously creates and adds chips to the container.'''

        for tag in ["Extra Soft", "Soft", "Medium", "Hard"]:
            await asynckivy.sleep(0)
            chip = MDChip(
                MDChipText(
                    text=tag,
                ),
                type="filter",
                md_bg_color="#303A29",

            )
            chip.bind(active=self.uncheck_chip)
            self.ids.chip_box.add_widget(chip)

    def uncheck_chip(self, current_chip: MDChip, active: bool) -> None:
        '''Removes a mark from an already marked chip.'''

        if active:
            for chip in self.ids.chip_box.children:
                if current_chip is not chip:
                    if chip.active:
                        chip.active = False


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = ChipScreen()

    def build(self) -> ChipScreen:
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "LightGreen"
        return self.screen

    def on_start(self) -> None:
        super().on_start()
        asynckivy.start(self.screen.create_chips())


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-filtering-single-select.gif
Input#

Input chips represent discrete pieces of information entered by a user, such as Gmail contacts or filter options within a search field.

They enable user input and verify that input by converting text into chips.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/input-chip.png
Example of input#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        type: "input"
        line_color: "grey"
        _no_ripple_effect: True

        MDChipLeadingAvatar:
            source: "data/logo/kivy-icon-128.png"

        MDChipText:
            text: "MDChip"

        MDChipTrailingIcon:
            icon: "close"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-input-chip.png
Suggestion#

Suggestion chips help narrow a user’s intent by presenting dynamically generated suggestions, such as possible responses or search filters.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/suggestion-chip.png
Example of suggestion#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        type: "suggestion"
        line_color: "grey"

        MDChipText:
            text: "MDChip"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-suggestion.png
API break#
1.2.0 version#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        text: "Portland"
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.on_release_chip(self)
'''


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

    def on_release_chip(self, instance_check):
        print(instance_check)


Test().run()
2.0.0 version#
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        line_color: "grey"
        on_release: app.on_release_chip(self)

        MDChipText:
            text: "MDChip"
'''


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

    def on_release_chip(self, instance_check):
        print(instance_check)


Example().run()
API - kivymd.uix.chip.chip#
class kivymd.uix.chip.chip.MDChipLeadingAvatar(**kwargs)#

Implements the leading avatar for the chip.

For more information, see in the CircularRippleBehavior and ScaleBehavior and ButtonBehavior and MDIcon classes documentation.

class kivymd.uix.chip.chip.MDChipLeadingIcon(**kwargs)#

Implements the leading icon for the chip.

For more information, see in the CircularRippleBehavior and ScaleBehavior and ButtonBehavior and MDIcon classes documentation.

class kivymd.uix.chip.chip.MDChipTrailingIcon(**kwargs)#

Implements the trailing icon for the chip.

For more information, see in the CircularRippleBehavior and ScaleBehavior and ButtonBehavior and MDIcon classes documentation.

class kivymd.uix.chip.chip.MDChipText(*args, **kwargs)#

Implements the label for the chip.

For more information, see in the MDLabel classes documentation.

text_color_disabled#

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

New in version 2.0.0.

text_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.chip.chip.MDChip(*args, **kwargs)#

Chip class.

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

radius#

Chip radius.

radius is an VariableListProperty and defaults to [dp(8), dp(8), dp(8), dp(8)].

type#

Type of chip.

New in version 2.0.0.

Available options are: ‘assist’, ‘filter’, ‘input’, ‘suggestion’.

type is an OptionProperty and defaults to ‘suggestion’.

active#

Whether the check is marked or not.

New in version 1.0.0.

active is an BooleanProperty and defaults to False.

selected_color#

The background color of the chip in the marked state in (r, g, b, a) or string format.

New in version 2.0.0.

selected_color is an ColorProperty and defaults to None.

line_color_disabled#

The color of the outline in the disabled state

New in version 2.0.0.

line_color_disabled is an ColorProperty and defaults to None.

on_long_touch(*args) None#

Fired when the widget is pressed for a long time.

on_line_color(instance, value) None#

Fired when the values of line_color change.

on_type(instance, value: str) None#

Fired when the values of type change.

on_active(instance_check, active_value: bool) None#

Called when the values of active change.

complete_anim_ripple(*args) None#

Called at the end of the ripple animation.

remove_marked_icon_from_chip() None#
add_marked_icon_to_chip() None#

Adds and animates a check icon to the chip.

set_chip_bg_color(color: list | str) None#

Animates the background color of the chip.

on_press(*args) None#

Fired when the button is pressed.

on_release(*args) None#

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

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)

BottomSheet#

#

Bottom sheets are surfaces containing supplementary content that are anchored to the bottom of the screen.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet.png
Usage#
Root:

    MDNavigationLayout:

        MDScreenManager:

            [...]

        MDBottomSheet:

The bottom sheet has two types:

Standard#

Standard bottom sheets co-exist with the screen’s main UI region and allow for simultaneously viewing and interacting with both regions, especially when the main UI region is frequently scrolled or panned.

Use a standard bottom sheet to display content that complements the screen’s primary content, such as an audio player in a music app.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-standard.gif

Standard bottom sheets are elevated above the main UI region so their visibility is not affected by panning or scrolling.

Add elements to MDBottomSheetDragHandleTitle class#
MDBottomSheet:

    MDBottomSheetDragHandle:

        MDBottomSheetDragHandleTitle:
            text: "MDBottomSheet"
            adaptive_height: True
            pos_hint: {"center_y": .5}

        MDBottomSheetDragHandleButton:
            icon: "close"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-drag-handle-elements.png
A practical example with standard bottom sheet#

(A double tap on the map to open the bottom sheet)

import asynckivy

from kivy.lang import Builder
from kivy.properties import StringProperty, ObjectProperty, BooleanProperty
from kivy_garden.mapview import MapView

from kivymd.app import MDApp
from kivymd.uix.behaviors import TouchBehavior
from kivymd.uix.boxlayout import MDBoxLayout

KV = '''
#:import MapSource kivy_garden.mapview.MapSource
#:import asynckivy asynckivy


<TypeMapElement>
    orientation: "vertical"
    adaptive_height: True
    spacing: "8dp"

    MDIconButton:
        id: icon
        icon: root.icon
        theme_bg_color: "Custom"
        md_bg_color: "#EDF1F9" if not root.selected else app.theme_cls.primaryColor
        pos_hint: {"center_x": .5}
        theme_icon_color: "Custom"
        icon_color: "white" if root.selected else "black"
        on_release: app.set_active_element(root, root.title.lower())

    MDLabel:
        text: root.title
        pos_hint: {"center_x": .5}
        halign: "center"
        adaptive_height: True


MDScreen:

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                CustomMapView:
                    bottom_sheet: bottom_sheet
                    map_source: MapSource(url=app.map_sources[app.current_map])
                    lat: 46.5124
                    lon: 47.9812
                    zoom: 12

        MDBottomSheet:
            id: bottom_sheet
            sheet_type: "standard"
            size_hint_y: None
            height: "150dp"
            on_open: asynckivy.start(app.generate_content())

            MDBottomSheetDragHandle:
                drag_handle_color: "grey"

                MDBottomSheetDragHandleTitle:
                    text: "Select type map"
                    pos_hint: {"center_y": .5}

                MDBottomSheetDragHandleButton:
                    icon: "close"
                    ripple_effect: False
                    on_release: bottom_sheet.set_state("toggle")

            BoxLayout:
                id: content_container
                padding: 0, 0, 0, "16dp"
'''


class TypeMapElement(MDBoxLayout):
    selected = BooleanProperty(False)
    icon = StringProperty()
    title = StringProperty()


class CustomMapView(MapView, TouchBehavior):
    bottom_sheet = ObjectProperty()

    def on_double_tap(self, touch, *args):
        if self.bottom_sheet:
            self.bottom_sheet.set_state("toggle")


class Example(MDApp):
    map_sources = {
        "street": "https://mt1.google.com/vt/lyrs=m&x={x}&y={y}&z={z}",
        "sputnik": "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
        "hybrid": "https://mt1.google.com/vt/lyrs=y&x={x}&y={y}&z={z}",
    }
    current_map = StringProperty("street")

    async def generate_content(self):
        icons = {
            "street": "google-street-view",
            "sputnik": "space-station",
            "hybrid": "map-legend",
        }
        if not self.root.ids.content_container.children:
            for i, title in enumerate(self.map_sources.keys()):
                await asynckivy.sleep(0)
                self.root.ids.content_container.add_widget(
                    TypeMapElement(
                        title=title.capitalize(),
                        icon=icons[title],
                        selected=not i,
                    )
                )

    def set_active_element(self, instance, type_map):
        for element in self.root.ids.content_container.children:
            if instance == element:
                element.selected = True
                self.current_map = type_map
            else:
                element.selected = False

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


Example().run()
API break#
1.2.0 version#
Root:

    MDBottomSheet:

        # Optional.
        MDBottomSheetDragHandle:

            # Optional.
            MDBottomSheetDragHandleTitle:

            # Optional.
            MDBottomSheetDragHandleButton:

        MDBottomSheetContent:
            [...]
2.0.0 version#
Root:

    MDNavigationLayout:

        MDScreenManager:

            # Your screen.
            MDScreen:

        MDBottomSheet:

            # Optional.
            MDBottomSheetDragHandle:

                # Optional.
                MDBottomSheetDragHandleTitle:

                # Optional.
                MDBottomSheetDragHandleButton:
                    icon: "close"

            # Your content.
            BoxLayout:
API - kivymd.uix.bottomsheet.bottomsheet#
class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandleButton(**kwargs)#

Implements a close button (or other functionality) for the MDBottomSheetDragHandle container.

For more information, see in the MDIconButton class documentation.

New in version 1.2.0.

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandleTitle(*args, **kwargs)#

Implements a header for the MDBottomSheetDragHandle container.

For more information, see in the MDLabel class documentation.

New in version 1.2.0.

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandle(**kwargs)#

Implements a container that can place the header of the bottom sheet and the close button. Also implements the event of dragging the bottom sheet on the parent screen.

For more information, see in the BoxLayout class documentation.

New in version 1.2.0.

drag_handle_color#

Color of drag handle element in (r, g, b, a) or string format.

MDBottomSheet:

    MDBottomSheetDragHandle:
        drag_handle_color: "white"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-sheet-drag-handle-color.png

drag_handle_color is an ColorProperty and defaults to None.

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.bottomsheet.bottomsheet.MDBottomSheet(*args, **kwargs)#

Bottom sheet class.

For more information, see in the MDNavigationDrawer class documentation.

sheet_type#

Type of sheet.

Standard bottom sheets co-exist with the screen’s main UI region and allow for simultaneously viewing and interacting with both regions, especially when the main UI region is frequently scrolled or panned. Use a standard bottom sheet to display content that complements the screen’s primary content, such as an audio player in a music app.

Like dialogs, modal bottom sheets appear in front of app content, disabling all other app functionality when they appear, and remaining on screen until confirmed, dismissed, or a required action has been taken.

Changed in version 2.0.0: Rename from type to sheet_type.

sheet_type is a OptionProperty and defaults to ‘modal’.

on_sheet_type(instance, value) None#

Fired when the sheet_type value 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)
on_touch_move(touch)#

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

Slider#

#

Sliders allow users to make selections from a range of values.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/slider.png
  • Sliders should present the full range of choices that are available

  • Two types: continuous and discrete

  • The slider should immediately reflect any input made by a user

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliders-types.png
  1. Continuous slider

  2. Discrete slider

Usage#
MDSlider(
    MDSliderHandle(
    ),
    MDSliderValueLabel(
    ),
    step=10,
    value=50,
)
MDSlider:
    step: 10
    value: 50

    MDSliderHandle:

    MDSliderValueLabel:
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/slider-anatomy.png
API - kivymd.uix.slider.slider#
class kivymd.uix.slider.slider.MDSlider(*args, **kwargs)#

Slider class.

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

track_active_width#

Width of the active track.

New in version 2.0.0.

track_active_width is an NumericProperty and defaults to dp(4).

track_inactive_width#

Width of the inactive track.

New in version 2.0.0.

track_inactive_width is an NumericProperty and defaults to dp(4).

step_point_size#

Step point size.

New in version 2.0.0.

step_point_size is an NumericProperty and defaults to dp(1).

track_active_color#

Color of the active track.

New in version 2.0.0.

Changed in version 2.0.0: Rename from track_color_active to track_active_color

track_active_color is an ColorProperty and defaults to None.

track_active_step_point_color#

Color of step points on active track.

New in version 2.0.0.

track_active_step_point_color is an ColorProperty and defaults to None.

track_inactive_step_point_color#

Color of step points on inactive track.

New in version 2.0.0.

track_inactive_step_point_color is an ColorProperty and defaults to None.

track_inactive_color#

Color of the inactive track.

New in version 2.0.0.

Changed in version 2.0.0: Rename from track_color_inactive to track_inactive_color

track_active_color is an ColorProperty and defaults to None.

value_container_show_anim_duration#

Duration of the animation opening of the label value.

New in version 2.0.0.

value_container_show_anim_duration is an NumericProperty and defaults to 0.2.

value_container_hide_anim_duration#

Duration of closing the animation of the label value.

New in version 2.0.0.

value_container_hide_anim_duration is an NumericProperty and defaults to 0.2.

value_container_show_anim_transition#

The type of the opening animation of the label value.

New in version 2.0.0.

value_container_show_anim_transition is an StringProperty and defaults to ‘out_circ’.

value_container_hide_anim_transition#

The type of the closing animation of the label value.

New in version 2.0.0.

value_container_hide_anim_transition is an StringProperty and defaults to ‘out_circ’.

handle_anim_transition#

Handle animation type.

New in version 2.0.0.

handle_anim_transition is an StringProperty and defaults to ‘out_circ’.

handle_anim_duration#

Handle animation duration.

New in version 2.0.0.

handle_anim_duration is an NumericProperty and defaults to 0.2.

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)
update_points(instance, step) None#

Draws the step points on the slider.

on_size(*args) None#

Fired when the widget is resized.

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_value_pos(*args) None#

Fired when the value_pos value changes. Sets a new value for the value label texture.

on_touch_up(touch)#

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_move(touch)#

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_handle_enter() None#

Scales the container of the label value.

on_handle_leave() None#

Scales the container of the label value.

class kivymd.uix.slider.slider.MDSliderHandle(**kwargs)#

Handle class.

New in version 2.0.0.

For more information, see in the ThemableBehavior and BackgroundColorBehavior and FocusBehavior and Widget classes documentation.

radius#

Handle radius.

radius is an VariableListProperty and defaults to [dp(10), dp(10), dp(10), dp(10)].

size#

Handle size.

size is an ListProperty and defaults to [dp(20), dp(20)].

state_layer_size#

Handle state layer size.

state_layer_size is an ListProperty and defaults to [dp(40), dp(40)].

state_layer_color#

Handle state layer color.

state_layer_color is an ColorProperty and defaults to None.

on_enter() None#

Fired when mouse enter the bbox of the widget. Animates the display of the slider handle layer.

on_leave() None#

Fired when the mouse goes outside the widget border. Animates the hiding of the slider handle layer.

class kivymd.uix.slider.slider.MDSliderValueLabel(*args, **kwargs)#

Implements the value label.

For more information, see in the MDLabel class documentation.

New in version 2.0.0.

size#

Container size for the label value.

handle_anim_transition is an ListProperty and defaults to [dp(36), dp(36)].

SliverAppbar#

#

New in version 1.0.0.

MDSliverAppbar is a Material Design widget in KivyMD which gives scrollable or collapsible MDTopAppBar

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliver-appbar-preview.gif

Note

This widget is a modification of the silverappbar.py module.

Usage#
MDScreen:

    MDSliverAppbar:

        MDTopAppBar:
            [...]

        MDSliverAppbarHeader:

            # Custom content.
            [...]

        # Custom list.
        MDSliverAppbarContent:
Anatomy#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliver-appbar-anatomy.png
Example#
from kivy.lang.builder import Builder

from kivymd.app import MDApp
from kivymd.uix.list import MDListItem

KV = '''
<GuitarItem>
    theme_bg_color: "Custom"
    md_bg_color: "2d4a50"

    MDListItemLeadingAvatar
        source: "avatar.png"

    MDListItemHeadlineText:
        text: "Ibanez"

    MDListItemSupportingText:
        text: "GRG121DX-BKF"

    MDListItemTertiaryText:
        text: "$445,99"

    MDListItemTrailingIcon:
        icon: "guitar-electric"


MDScreen:

    MDSliverAppbar:
        background_color: "2d4a50"
        hide_appbar: True

        MDTopAppBar:
            type: "medium"

            MDTopAppBarLeadingButtonContainer:

                MDActionTopAppBarButton:
                    icon: "arrow-left"

            MDTopAppBarTitle:
                text: "Sliver toolbar"

            MDTopAppBarTrailingButtonContainer:

                MDActionTopAppBarButton:
                    icon: "attachment"

                MDActionTopAppBarButton:
                    icon: "calendar"

                MDActionTopAppBarButton:
                    icon: "dots-vertical"

        MDSliverAppbarHeader:

            FitImage:
                source: "bg.jpg"

        MDSliverAppbarContent:
            id: content
            orientation: "vertical"
            padding: "12dp"
            theme_bg_color: "Custom"
            md_bg_color: "2d4a50"
'''


class GuitarItem(MDListItem):
    ...


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

    def on_start(self):
        super().on_start()
        for x in range(10):
            self.root.ids.content.add_widget(GuitarItem())


Example().run()
API break#
1.2.0 version#
#:import SliverToolbar __main__.SliverToolbar

Root:

    MDSliverAppbar:
        [...]

        MDSliverAppbarHeader:

            [...]

        MDSliverAppbarContent:
            [...]
class SliverToolbar(MDTopAppBar):
    [...]
2.0.0 version#
Root:

    MDSliverAppbar:
        [...]

        MDTopAppBar:
            [...]

        MDSliverAppbarHeader:

            [...]

        MDSliverAppbarContent:
            [...]
API - kivymd.uix.sliverappbar.sliverappbar#
class kivymd.uix.sliverappbar.sliverappbar.MDSliverAppbarContent(*args, **kwargs)#

Implements a box for a scrollable list of custom items.

For more information, see in the MDBoxLayout class documentation.

class kivymd.uix.sliverappbar.sliverappbar.MDSliverAppbarHeader(**kwargs)#

Sliver app bar header class.

For more information, see in the BoxLayout class documentation.

class kivymd.uix.sliverappbar.sliverappbar.MDSliverAppbar(**kwargs)#

Sliver appbar class.

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

Events:
on_scroll_content

Fired when the list of custom content is being scrolled.

background_color#

Background color of appbar in (r, g, b, a) or string format.

background_color is an ColorProperty and defaults to None.

max_height#

Distance from top of screen to start of custom list content.

MDSliverAppbar:
    max_height: "200dp"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliver-appbar-max-height.png

max_height is an NumericProperty and defaults to Window.height / 2.

hide_appbar#

Whether to hide the appbar when scrolling through a list of custom content.

Changed in version 2.0.0: Rename hide_toolbar to hide_appbar attribute.

MDSliverAppbar:
    hide_appbar: False
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliver-appbar-hide-appbar-false.gif
MDSliverAppbar:
    hide_appbar: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliver-appbar-hide-appbar-true.gif

hide_appbar is an BooleanProperty and defaults to None.

radius#

Box radius for custom item list.

MDSliverAppbar:
    radius: 20
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliver-app-bar-radius.png

radius is an VariableListProperty and defaults to [20].

max_opacity#

Maximum background transparency value for the MDSliverAppbarHeader class.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliver-app-bar-max-opacity.gif
MDSliverAppbar:
    max_opacity: .5
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/sliver-app-bar-max-opacity-05.gif

max_opacity is an NumericProperty and defaults to 1.

on_hide_appbar(instance, value) None#

Fired when the hide_appbar value changes.

on_scroll_content(instance: object = None, value: float = 1.0, direction: str = 'up')#

Fired when the list of custom content is being scrolled.

Parameters:
on_background_color(instance, color) None#

Fired when the background_color value changes.

on_vbar() None#
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)
on__appbar(instance, value)#

NavigationRail#

#

New in version 1.0.0.

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

Navigation rails let people switch between UI views on mid-sized devices.

  • Can contain 3-7 destinations plus an optional FAB

  • Always put the rail in the same place, even on different screens of an app

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

from kivymd.app import MDApp
from kivymd.uix.navigationrail import MDNavigationRailItem

KV = '''
<CommonNavigationRailItem>

    MDNavigationRailItemIcon:
        icon: root.icon

    MDNavigationRailItemLabel:
        text: root.text


MDBoxLayout:

    MDNavigationRail:
        type: "selected"

        MDNavigationRailMenuButton:
            icon: "menu"

        MDNavigationRailFabButton:
            icon: "home"

        CommonNavigationRailItem:
            icon: "folder-outline"
            text: "Files"

        CommonNavigationRailItem:
            icon: "bookmark-outline"
            text: "Bookmark"

        CommonNavigationRailItem:
            icon: "library-outline"
            text: "Library"

    MDScreen:
        md_bg_color: self.theme_cls.secondaryContainerColor
'''


class CommonNavigationRailItem(MDNavigationRailItem):
    text = StringProperty()
    icon = StringProperty()


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-usage.png
Anatomy#
MDNavigationRail:

    # Optional.
    MDNavigationRailMenuButton:
        icon: "menu"

    # Optional.
    MDNavigationRailFabButton:
        icon: "home"

    MDNavigationRailItem

        MDNavigationRailItemIcon:
            icon: icon

        MDNavigationRailItemLabel:
            text: text

    [...]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-anatomy.png
Anatomy item#
MDNavigationRailItem

    MDNavigationRailItemIcon:
        icon: icon

    MDNavigationRailItemLabel:
        text: text
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-anatomy-item.png
Configurations#
Rail types#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type.png
  1. Selected

  2. Unselected

  3. Labeled

Selected#
MDNavigationRail:
    type: "selected"  # default
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-selected.gif
Unselected#
MDNavigationRail:
    type: "unselected"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-unselected.gif
Labeled#
MDNavigationRail:
    type: "labeled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-labeled.gif
Rail anchored#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-anchored.png
  1. Top

  2. Center

  3. Bottom

Top#
MDNavigationRail:
    anchor: "top"
Center#
MDNavigationRail:
    anchor: "center"  # default
Bottom#
MDNavigationRail:
    anchor: "bottom"
API break#
1.2.0 version#
MDNavigationRail:

    MDNavigationRailMenuButton:
        icon: "menu"

    MDNavigationRailFabButton:
        icon: "home"

    MDNavigationRailItem:
        icon: icon
        text: text

    [...]
2.2.0 version#
MDNavigationRail:

    MDNavigationRailMenuButton:
        icon: "menu"

    MDNavigationRailFabButton:
        icon: "home"

    MDNavigationRailItem

        MDNavigationRailItemIcon:
            icon: icon

        MDNavigationRailItemLabel:
            text: text

    [...]
API - kivymd.uix.navigationrail.navigationrail#
class kivymd.uix.navigationrail.navigationrail.MDNavigationRailFabButton(**kwargs)#

Implements a floating action button (FAB).

For more information, see in the MDFabButton class documentation.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailMenuButton(**kwargs)#

Implements a menu button.

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 switch when the widget is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailItemIcon(*args, **kwargs)#

Implements an icon for the MDNavigationRailItem class.

For more information, see in the RectangularRippleBehavior and MDIcon classes documentation.

Changed in version 2.0.0.

active_indicator_color#

Background color of the active indicator in (r, g, b, a) or string format.

active_indicator_color is an ColorProperty and defaults to None.

anim_complete(*args)#

Fired when the “fade_out” animation complete.

lay_canvas_instructions() None#

Adds graphic instructions to the canvas to implement ripple animation.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailItemLabel(*args, **kwargs)#

Implements an label for the MDNavigationRailItem class.

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

Changed in version 2.0.0.

scale_value_y#

Y-axis value.

scale_value_y is an NumericProperty and defaults to 0.

on__active(instance, value) None#

Fired when the _active value changes.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailItem(*args, **kwargs)#

Implements a menu item with an icon and text.

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

active#

Is the element active.

active is an BooleanProperty and defaults to False.

radius#

Item radius.

Changed in version 2.0.0.

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

on_active(instance, value) None#

Fired when the active value changes.

on_enter(*args) None#

Fired when mouse enter the bbox of the widget.

on_leave(*args) None#

Fired when the mouse goes outside the widget border.

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.navigationrail.navigationrail.MDNavigationRail(*args, **kwargs)#

Navigation rail class.

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

radius#

Rail radius.

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

anchor#

The position of the panel with menu items. Available options are: ‘top’, ‘bottom’, ‘center’.

anchor is an OptionProperty and defaults to ‘top’.

type#

Type of switching menu items. Available options are: ‘labeled’, ‘selected’, ‘unselected’.

type is an OptionProperty and defaults to ‘labeled’.

fab_button: MDNavigationRailFabButton#
menu_button: MDNavigationRailFabButton#
on_size(*args) None#

Fired when the application screen size changes.

get_items() list#

Returns a list of MDNavigationRailItem objects.

set_active_item(item: MDNavigationRailItem) None#

Sets the active menu list 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.

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)

Tabs#

#

Tabs organize content across different screens, data sets, and other interactions.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-preview.png
  • Use tabs to group content into helpful categories

  • Two types: primary and secondary

  • Tabs can horizontally scroll, so a UI can have as many tabs as needed

  • Place tabs next to each other as peers

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-types.png
  1. Primary tabs

  2. Secondary tabs

Usage primary tabs#

Primary tabs should be used when just one set of tabs are needed.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import (
    MDTabsItem,
    MDTabsItemIcon,
    MDTabsItemText,
    MDTabsBadge,
)

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

    MDTabsPrimary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}

        MDDivider:
'''


class Example(MDApp):
    def on_start(self):
        super().on_start()
        for tab_icon, tab_name in {
            "airplane": "Flights",
            "treasure-chest": "Trips",
            "compass-outline": "Explore",
        }.items():
            if tab_icon == "treasure-chest":
                self.root.ids.tabs.add_widget(
                    MDTabsItem(
                        MDTabsItemIcon(
                            MDTabsBadge(
                                text="99",
                            ),
                            icon=tab_icon,
                        ),
                        MDTabsItemText(
                            text=tab_name,
                        ),
                    )
                )
            else:
                self.root.ids.tabs.add_widget(
                    MDTabsItem(
                        MDTabsItemIcon(
                            icon=tab_icon,
                        ),
                        MDTabsItemText(
                            text=tab_name,
                        ),
                    )
                )
            self.root.ids.tabs.switch_tab(icon="airplane")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-usage.png
Anatomy primary tabs#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-anatomy.png
Usage secondary tabs#

Secondary tabs are necessary when a screen requires more than one level of tabs. These tabs use a simpler style of indicator, but their function is identical to primary tabs.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import (
    MDTabsItemIcon,
    MDTabsItemText,
    MDTabsBadge, MDTabsItemSecondary,
)

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

    MDTabsSecondary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}

        MDDivider:
'''


class Example(MDApp):
    def on_start(self):
        super().on_start()
        for tab_icon, tab_name in {
            "airplane": "Flights",
            "treasure-chest": "Trips",
            "compass-outline": "Explore",
        }.items():
            if tab_icon == "treasure-chest":
                self.root.ids.tabs.add_widget(
                    MDTabsItemSecondary(
                        MDTabsItemIcon(
                            icon=tab_icon,
                        ),
                        MDTabsItemText(
                            text=tab_name,
                        ),
                        MDTabsBadge(
                            text="5",
                        ),
                    )
                )
            else:
                self.root.ids.tabs.add_widget(
                    MDTabsItemSecondary(
                        MDTabsItemIcon(
                            icon=tab_icon,
                        ),
                        MDTabsItemText(
                            text=tab_name,
                        ),
                    )
                )
        self.root.ids.tabs.switch_tab(icon="airplane")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()
Anatomy secondary tabs#
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-secondary-anatomy.png
Behaviors#
Scrollable tabs#

When a set of tabs cannot fit on screen, use scrollable tabs. Scrollable tabs can use longer text labels and a larger number of tabs. They are best used for browsing on touch interfaces.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsItemText, MDTabsItem

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

    MDTabsPrimary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint_x: .6
        allow_stretch: False
        label_only: True

        MDDivider:
'''


class Example(MDApp):
    def on_start(self):
        super().on_start()
        for tab_name in [
            "Moscow",
            "Saint Petersburg",
            "Novosibirsk",
            "Yekaterinburg",
            "Kazan",
            "Nizhny Novgorod",
            "Chelyabinsk",
        ]:
            self.root.ids.tabs.add_widget(
                MDTabsItem(
                    MDTabsItemText(
                        text=tab_name,
                    ),
                )
            )
        self.root.ids.tabs.switch_tab(text="Moscow")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-scrollable-behavior.gif
Fixed tabs#

Fixed tabs display all tabs in a set simultaneously. They are best for switching between related content quickly, such as between transportation methods in a map. To navigate between fixed tabs, tap an individual tab, or swipe left or right in the content area.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsItemText, MDTabsItem

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

    MDTabsPrimary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint_x: .6
        allow_stretch: True
        label_only: True

        MDDivider:
'''


class Example(MDApp):
    def on_start(self):
        super().on_start()
        for tab_name in [
            "Moscow", "Saint Petersburg", "Novosibirsk"
        ]:
            self.root.ids.tabs.add_widget(
                MDTabsItem(
                    MDTabsItemText(
                        text=tab_name,
                    ),
                )
            )
        self.root.ids.tabs.switch_tab(text="Moscow")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-fixed-behavior.png
Tap a tab#

Navigate to a tab by tapping on it.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-tap-a-tab-behavior.gif
Swipe within the content area#

To navigate between tabs, users can swipe left or right within the content area.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-swipe-within-content-area-behavior.gif
Switching tab#

You can switch tabs by icon name, by tab name, and by tab objects:

instance_tabs.switch_tab(icon="airplane")
instance_tabs.switch_tab(text="Airplane")
instance_tabs.switch_tab(
    instance=instance_tabs_item  # MDTabsItem
)
API break#
1.2.0 version#
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.tab import MDTabsBase
from kivymd.icon_definitions import md_icons

KV = '''
MDBoxLayout:

    MDTabs:
        id: tabs
        on_ref_press: app.on_ref_press(*args)


<Tab>

    MDIconButton:
        id: icon
        icon: app.icons[0]
        icon_size: "48sp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Tab(MDFloatLayout, MDTabsBase):
    '''Class implementing content for a tab.'''


class Example(MDApp):
    icons = list(md_icons.keys())[15:30]

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

    def on_start(self):
        super().on_start()
        for name_tab in self.icons:
            self.root.ids.tabs.add_widget(
                Tab(title=name_tab, icon=name_tab)
            )


Example().run()
2.0.0 version#
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.icon_definitions import md_icons
from kivymd.uix.label import MDIcon
from kivymd.uix.tab import MDTabsItem, MDTabsItemIcon
from kivymd.uix.tab.tab import MDTabsItemText

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

    MDTabsPrimary:
        id: tabs
        allow_stretch: False
        pos_hint: {"center_x": .5, "center_y": .5}

        MDDivider:

        MDTabsCarousel:
            id: related_content
            size_hint_y: None
            height: root.height - tabs.ids.tab_scroll.height
'''


class Example(MDApp):
    def on_start(self):
        super().on_start()
        for name_tab in list(md_icons.keys())[15:30]:
            self.root.ids.tabs.add_widget(
                MDTabsItem(
                    MDTabsItemIcon(
                        icon=name_tab,
                    ),
                    MDTabsItemText(
                        text=name_tab,
                    ),
                )
            )
            self.root.ids.related_content.add_widget(
                MDIcon(
                    icon=name_tab,
                    pos_hint={"center_x": 0.5, "center_y": 0.5},
                )
            )
            self.root.ids.tabs.switch_tab(icon="airplane")

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


Example().run()
API - kivymd.uix.tab.tab#
class kivymd.uix.tab.tab.MDTabsBadge(*args, **kwargs)#

Implements an badge for secondary tabs.

New in version 2.0.0.

For more information, see in the MDBadge class documentation.

class kivymd.uix.tab.tab.MDTabsCarousel(**kwargs)#

Implements a carousel for user-generated content.

For more information, see in the Carousel class documentation.

lock_swiping#

If True - disable switching tabs by swipe.

lock_swiping is an BooleanProperty and defaults to False.

on_touch_move(touch) str | bool | None#

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

class kivymd.uix.tab.tab.MDTabsItemText(*args, **kwargs)#

Implements an label for the MDTabsItem class.

For more information, see in the MDLabel class documentation.

New in version 2.0.0.

class kivymd.uix.tab.tab.MDTabsItemIcon(*args, **kwargs)#

Implements an icon for the MDTabsItem class.

For more information, see in the MDIcon class documentation.

New in version 2.0.0.

class kivymd.uix.tab.tab.MDTabsItem(*args, **kwargs)#

Implements a item with an icon and text for MDTabsPrimary class.

New in version 2.0.0.

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

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.tab.tab.MDTabsPrimary(*args, **kwargs)#

Tabs primary class.

Changed in version 2.0.0: Rename from MDTabs to MDTabsPrimary class.

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

Events:
on_tab_switch

Fired when switching tabs.

md_bg_color#

The background color of the widget.

md_bg_color is an ColorProperty and defaults to None.

label_only#

Tabs with a label only or with an icon and a label.

New in version 2.0.0.

label_only is an BooleanProperty and defaults to False.

allow_stretch#

Whether to stretch tabs to the width of the panel.

allow_stretch is an BooleanProperty and defaults to True.

lock_swiping#

If True - disable switching tabs by swipe.

lock_swiping is an BooleanProperty and defaults to False.

anim_duration#

Duration of the slide animation.

anim_duration is an NumericProperty and defaults to 0.2.

indicator_anim#

Tab indicator animation. If you want use animation set it to True.

Changed in version 2.0.0: Rename from tab_indicator_anim to indicator_anim attribute.

indicator_anim is an BooleanProperty and defaults to True.

indicator_radius#

Radius of the tab indicator.

New in version 2.0.0.

indicator_radius is an VariableListProperty and defaults to [dp(2), dp(2), 0, 0].

indicator_height#

Height of the tab indicator.

Changed in version 2.0.0: Rename from tab_indicator_height to indicator_height attribute.

indicator_height is an NumericProperty and defaults to ‘4dp’.

indicator_duration#

The duration of the animation of the indicator movement when switching tabs.

New in version 2.0.0.

indicator_duration is an NumericProperty and defaults to 0.5.

indicator_transition#

The transition name of animation of the indicator movement when switching tabs.

New in version 2.0.0.

indicator_transition is an StringProperty and defaults to `’out_expo’.

last_scroll_x#

Is the carousel reference of the next tab/slide. When you go from ‘Tab A’ to ‘Tab B’, ‘Tab B’ will be the target tab/slide of the carousel.

last_scroll_x is an AliasProperty.

target#

It is the carousel reference of the next tab / slide. When you go from ‘Tab A’ to ‘Tab B’, ‘Tab B’ will be the target tab / slide of the carousel.

target is an ObjectProperty and default to None.

indicator#

It is the SmoothRoundedRectangle instruction reference of the tab indicator.

indicator is an AliasProperty.

get_last_scroll_x()#
get_rect_instruction()#
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)
do_autoscroll_tabs(instance: MDTabsItem, value: float) None#

Automatically scrolls the list of tabs when swiping the carousel slide (related content).

Changed in version 2.0.0: Rename from tab_bar_autoscroll to do_autoscroll_tabs method.

android_animation(instance: MDTabsCarousel, offset: float) None#

Fired when swiping a carousel slide (related content).

update_indicator(x: float = 0.0, w: float = 0.0, instance: MDTabsItem = None) None#

Update position and size of the indicator.

switch_tab(instance: MDTabsItem = None, text: str = '', icon: str = '') None#

Switches tabs by tab object/tab text/tab icon name.

set_active_item(item: MDTabsItem) None#

Sets the active tab item.

get_tabs_list() list#

Returns a list of MDTabsItem objects.

Changed in version 2.0.0: Rename from get_tab_list to get_tabs_list method.

get_slides_list() list#

Returns a list of user tab objects.

Changed in version 2.0.0: Rename from get_slides to get_slides_list method.

get_current_tab() MDTabsItem#

Returns current tab object.

New in version 1.0.0.

Returns the carousel slide object (related content).

New in version 2.0.0.

on_tab_switch(*args) None#

This event is launched every time the current tab is changed.

on_slide_progress(*args) None#

This event is deployed every available frame while the tab is scrolling.

Fired when the Tab index have changed. This event is deployed by the builtin carousel of the class.

on_size(instance, size) None#

Fired when the application screen size changes.

class kivymd.uix.tab.tab.MDTabsItemSecondary(*args, **kwargs)#

Implements a item with an icon and text for MDTabsSecondary class.

New in version 2.0.0.

For more information, see in the MDTabsItemBase and AnchorLayout classes documentation.

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.tab.tab.MDTabsSecondary(*args, **kwargs)#

Tabs secondary class.

New in version 2.0.0.

For more information, see in the MDTabsPrimary class documentation.

indicator_radius#

Radius of the tab indicator.

indicator_radius is an VariableListProperty and defaults to [0, 0, 0, 0].

indicator_height#

Height of the tab indicator.

indicator_height is an NumericProperty and defaults to ‘2dp’.

Label#

#

The MDLabel widget is for rendering text.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/label.png
MDLabel#
Example#
from kivy.lang import Builder

from kivymd.app import MDApp

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

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


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/label-example.png

To use a custom color for MDLabel, use a theme ‘Custom’. After that, you can specify the desired color in the text_color parameter:

MDLabel:
    text: "Custom color"
    halign: "center"
    theme_text_color: "Custom"
    text_color: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-custom-color.png

MDLabel provides standard font styles for labels. To do this, specify the name of the desired style in the font_style and role parameters:

MDLabel:
    text: "Display, role - 'large'"
    font_style: "Display"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-font-style-display-large.png
MDLabel:
    text: "Display, role - 'small'"
    font_style: "Display"
    role: "small"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-font-style-display-small.png
All styles#
from kivy.lang import Builder

from kivymd.font_definitions import theme_font_styles
from kivymd.app import MDApp

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

    MDRecycleView:
        id: rv
        key_viewclass: 'viewclass'
        key_size: 'height'

        RecycleBoxLayout:
            padding: dp(10)
            spacing: dp(10)
            default_size: None, dp(48)
            default_size_hint: 1, None
            size_hint_y: None
            height: self.minimum_height
            orientation: "vertical"
'''


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

    def on_start(self):
        super().on_start()
        for style in theme_font_styles:
            if style != "Icon":
                for role in theme_font_styles[style]:
                    font_size = int(theme_font_styles[style][role]["font-size"])
                    self.root.ids.rv.data.append(
                        {
                            "viewclass": "MDLabel",
                            "text": f"{style} {role} {font_size} sp",
                            "adaptive_height": "True",
                            "font_style": style,
                            "role": role,
                        }
                    )


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/label-font-style-preview.png
Highlighting and copying labels#
You can highlight labels by double tap on the label:#
from kivy.lang.builder import Builder

from kivymd.app import MDApp

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

    MDLabel:
        adaptive_size: True
        pos_hint: {"center_x": .5, "center_y": .5}
        text: "Do a double click on me"
        allow_selection: True
        padding: "4dp", "4dp"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-allow-selection.gif
You can copy the label text by double clicking on it:#
from kivy.lang.builder import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDLabel:
        adaptive_size: True
        pos_hint: {"center_x": .5, "center_y": .5}
        text: "MDLabel"
        padding: "4dp", "4dp"
        allow_selection: True
        allow_copy: True
        on_copy: print("The text is copied to the clipboard")
'''


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


Example().run()
Example of copying/cutting labels using the context menu#
from kivy.core.clipboard import Clipboard
from kivy.lang.builder import Builder
from kivy.metrics import dp

from kivymd.uix.snackbar import MDSnackbar, MDSnackbarText
from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.uix.menu import MDDropdownMenu

KV = '''
MDBoxLayout:
    orientation: "vertical"
    spacing: "12dp"
    padding: "24dp"
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        id: box
        orientation: "vertical"
        padding: "24dp"
        spacing: "12dp"
        adaptive_height: True

    MDTextField:
        max_height: "200dp"
        mode: "filled"
        multiline: True

    Widget:
'''

data = [
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "Sed blandit libero volutpat sed cras ornare arcu. Nisl vel pretium "
    "lectus quam id leo in. Tincidunt arcu non sodales neque sodales ut etiam.",
    "Elit scelerisque mauris pellentesque pulvinar pellentesque habitant. "
    "Nisl rhoncus mattis rhoncus urna neque. Orci nulla pellentesque "
    "dignissim enim. Ac auctor augue mauris augue neque gravida in fermentum. "
    "Lacus suspendisse faucibus interdum posuere."
]


def toast(text):
    MDSnackbar(
        MDSnackbarText(
            text=text,
        ),
        y=dp(24),
        pos_hint={"center_x": 0.5},
        size_hint_x=0.3,
    ).open()


class CopyLabel(MDLabel):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.allow_selection = True
        self.adaptive_height = True


class Example(MDApp):
    context_menu = None

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

    def on_start(self):
        super().on_start()
        for text in data:
            copy_label = CopyLabel(text=text)
            copy_label.bind(on_selection=self.open_context_menu)
            self.root.ids.box.add_widget(copy_label)

    def click_item_context_menu(
        self, type_click: str, instance_label: CopyLabel
    ) -> None:
        Clipboard.copy(instance_label.text)

        if type_click == "copy":
            toast("Copied")
        elif type_click == "cut":
            self.root.ids.box.remove_widget(instance_label)
            toast("Cut")
        if self.context_menu:
            self.context_menu.dismiss()

    def open_context_menu(self, instance_label: CopyLabel) -> None:
        instance_label.text_color = "black"
        menu_items = [
            {
                "text": "Copy text",
                "on_release": lambda: self.click_item_context_menu(
                    "copy", instance_label
                ),
            },
            {
                "text": "Cut text",
                "on_release": lambda: self.click_item_context_menu(
                    "cut", instance_label
                ),
            },
        ]
        self.context_menu = MDDropdownMenu(
            caller=instance_label, items=menu_items, width_mult=3
        )
        self.context_menu.open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/copying-cutting-labels-using-context-menu.gif
MDIcon#

You can use labels to display material design icons using the MDIcon class.

The MDIcon class is inherited from MDLabel and has the same parameters.

Warning

For the MDIcon class, you cannot use text and font_style options!

MDIcon:
    icon: "gmail"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-icon.png
MDIcon with badge icon#
MDIcon:
    icon: "gmail"

    MDBadge:
        text: "10+"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-icon-badge.png
MDIcon with a custom font icon#

You can use custom fonts to display icons. Such as for example Material Symbols. You can find the necessary fonts in the materialsymbols-python repository

from kivy.core.text import LabelBase
from kivy.lang import Builder
from kivy.metrics import sp

from kivymd.app import MDApp

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

    MDIcon:
        icon: "music_video"
        theme_font_name: "Custom"
        font_name: "MaterialSymbols"
        pos_hint: {"center_x": .5, "center_y": .58}

    MDButton:
        pos_hint: {"center_x": .5, "center_y": .47}

        MDButtonIcon:
            icon: "music_video"
            theme_font_name: "Custom"
            font_name: "MaterialSymbols"

        MDButtonText:
            text: "Elevated"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"

        LabelBase.register(
            name="MaterialSymbols",
            fn_regular="Material_Symbols_Outlined-20-200-1_200.ttf",
        )

        self.theme_cls.font_styles["MaterialSymbols"] = {
            "large": {
                "line-height": 1.64,
                "font-name": "MaterialSymbols",
                "font-size": sp(57),
            },
            "medium": {
                "line-height": 1.52,
                "font-name": "MaterialSymbols",
                "font-size": sp(45),
            },
            "small": {
                "line-height": 1.44,
                "font-name": "MaterialSymbols",
                "font-size": sp(36),
            },
        }

        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-icon-castom-font.png
API - kivymd.uix.label.label#
class kivymd.uix.label.label.MDLabel(*args, **kwargs)#

Label class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and Label and MDAdaptiveWidget and TouchBehavior and StateLayerBehavior classes documentation.

Events:
on_ref_press

Fired when the user clicks on a word referenced with a [ref] tag in a text markup.

on_copy

Fired when double-tapping on the label.

on_selection

Fired when double-tapping on the label.

on_cancel_selection

Fired when the highlighting is removed from the label text.

font_style#

Label font style.

Changed in version 2.0.0.

Available vanilla font_style are: ‘Display’, ‘Headline’, ‘Title’, ‘Label’, ‘Body’`.

font_style is an StringProperty and defaults to ‘Body’.

role#

Role of font style.

New in version 2.0.0.

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

role is an StringProperty and defaults to ‘large’.

text#

Text of the label.

text is an StringProperty and defaults to ‘’.

text_color#

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

text_color is an ColorProperty and defaults to None.

allow_copy#

Allows you to copy text to the clipboard by double-clicking on the label.

New in version 1.2.0.

allow_copy is an BooleanProperty and defaults to False.

allow_selection#

Allows to highlight text by double-clicking on the label.

New in version 1.2.0.

allow_selection is an BooleanProperty and defaults to False.

color_selection#

The color in (r, g, b, a) or string format of the text selection when the value of the allow_selection attribute is True.

New in version 1.2.0.

color_selection is an ColorProperty and defaults to None.

color_deselection#

The color in (r, g, b, a) or string format of the text deselection when the value of the allow_selection attribute is True.

New in version 1.2.0.

color_deselection is an ColorProperty and defaults to None.

is_selected#

Is the label text highlighted.

New in version 1.2.0.

is_selected is an BooleanProperty and defaults to False.

radius#

Label radius.

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

do_selection() None#
cancel_selection() None#
on_double_tap(touch, *args) None#

Fired by double-clicking on the widget.

on_window_touch(*args) None#

Fired at the on_touch_down event.

on_copy(*args) None#

Fired when double-tapping on the label.

New in version 1.2.0.

on_selection(*args) None#

Fired when double-tapping on the label.

New in version 1.2.0.

on_cancel_selection(*args) None#

Fired when the highlighting is removed from the label text.

New in version 1.2.0.

on_allow_selection(instance_label, selection: bool) None#

Fired when the allow_selection value changes.

on_text_color(instance_label, color: list | str) None#

Fired when the text_color value changes.

on_md_bg_color(instance_label, color: list | str) None#

Fired when the md_bg_color value changes.

on_size(instance_label, size: list) None#

Fired when the parent window of the application is resized.

update_canvas_bg_pos(instance_label, pos: list) None#
class kivymd.uix.label.label.MDIcon(*args, **kwargs)#

Icon class.

For more information, see in the MDLabel class documentation.

icon#

Label icon name.

icon is an StringProperty and defaults to ‘blank’.

source#

Path to icon.

source is an StringProperty and defaults to None.

icon_color#

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

New in version 2.0.0.

icon_color is a ColorProperty and defaults to None.

icon_color_disabled#

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

New in version 2.0.0.

icon_color_disabled is a ColorProperty and defaults to None.

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)

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.

New 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.

New 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.

New 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.

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.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.

New 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.

New 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.

Controllers#

WindowController#

#

New in version 1.0.0.

Modules and classes that implement useful methods for getting information about the state of the current application window.

Controlling the resizing direction of the application window#
# When resizing the application window, the direction of change will be
# printed - 'left' or 'right'.

from kivymd.app import MDApp
from kivymd.uix.controllers import WindowController
from kivymd.uix.screen import MDScreen


class MyScreen(MDScreen, WindowController):
    def on_width(self, *args):
        print(self.get_window_width_resizing_direction())


class Test(MDApp):
    def build(self):
        return MyScreen()


Test().run()
API - kivymd.uix.controllers.windowcontroller#
class kivymd.uix.controllers.windowcontroller.WindowController#
on_size(instance, size: list) None#

Called when the application screen size changes.

get_real_device_type() str#

Returns the device type - ‘mobile’, ‘tablet’ or ‘desktop’.

get_window_width_resizing_direction() str#

Return window width resizing direction - ‘left’ or ‘right’.

Behaviors#

Motion#

#

Use motion to make a UI expressive and easy to use.

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

New in version 1.2.0.

Classes of the Motion type implement the display behavior of widgets such as dialogs, dropdown menu, snack bars, and so on.

API - kivymd.uix.behaviors.motion_behavior#
class kivymd.uix.behaviors.motion_behavior.MotionBase#

Base class for widget display movement behavior.

show_transition#

The type of transition of the widget opening.

show_transition is a StringProperty and defaults to ‘linear’.

show_duration#

Duration of widget display transition.

show_duration is a NumericProperty and defaults to 0.2.

hide_transition#

The type of transition of the widget closing.

hide_transition is a StringProperty and defaults to ‘linear’.

hide_duration#

Duration of widget closing transition.

hide_duration is a NumericProperty and defaults to 0.2.

class kivymd.uix.behaviors.motion_behavior.MotionDropDownMenuBehavior(**kwargs)#

Base class for the dropdown menu movement behavior.

For more information, see in the MotionBase class documentation.

show_transition#

The type of transition of the widget opening.

show_transition is a StringProperty and defaults to ‘out_back’.

show_duration#

Duration of widget display transition.

show_duration is a NumericProperty and defaults to 0.2.

hide_transition#

The type of transition of the widget closing.

hide_transition is a StringProperty and defaults to ‘out_cubic’.

set_opacity() None#
set_scale() None#
on_dismiss() None#
on_open(*args)#
on__opacity(instance, value)#
on__scale_x(instance, value)#
on__scale_y(instance, value)#
class kivymd.uix.behaviors.motion_behavior.MotionExtendedFabButtonBehavior#

Base class for extended Fab button movement behavior.

For more information, see in the MotionBase class documentation.

show_transition#

The type of transition of the widget opening.

show_transition is a StringProperty and defaults to ‘out_circ’.

shift_transition#

Text label transition.

shift_transition is a StringProperty and defaults to ‘out_sine’.

show_duration#

Duration of widget display transition.

show_duration is a NumericProperty and defaults to 0.3.

hide_transition#

The type of transition of the widget closing.

hide_transition is a StringProperty and defaults to ‘linear’.

hide_duration#

Duration of widget closing transition.

hide_duration is a NumericProperty and defaults to 0.2.

collapse(*args) None#

Collapses the button.

expand(*args) None#

Expands the button.

set_opacity_text_button(value: int) None#
class kivymd.uix.behaviors.motion_behavior.MotionDialogBehavior#

Base class for dialog movement behavior.

For more information, see in the ScaleBehavior MotionBase classes documentation.

show_transition#

The type of transition of the widget opening.

show_transition is a StringProperty and defaults to ‘out_expo’.

show_button_container_transition#

The type of transition of the widget opening.

show_button_container_transition is a StringProperty and defaults to ‘out_circ’.

hide_transition#

The type of transition of the widget opening.

show_transition is a StringProperty and defaults to ‘hide_transition’.

show_duration#

Duration of widget display transition.

show_duration is a NumericProperty and defaults to 0.2.

on_dismiss(*args)#

Fired when a dialog closed.

on_open(*args)#

Fired when a dialog opened.

class kivymd.uix.behaviors.motion_behavior.MotionTimePickerBehavior#

Base class for time picker movement behavior.

For more information, see in the MotionPickerBehavior class documentation.

class kivymd.uix.behaviors.motion_behavior.MotionDatePickerBehavior#

Base class for date picker movement behavior.

For more information, see in the MotionPickerBehavior class documentation.

class kivymd.uix.behaviors.motion_behavior.MotionShackBehavior#

The base class for the behavior of the movement of snack bars.

For more information, see in the MotionBase class documentation.

on_dismiss(*args)#

Fired when a snackbar closed.

on_open(*args)#

Fired when a snackbar opened.

Magic#

#

Magical effects for buttons.

Warning

Magic effects do not work correctly with KivyMD buttons!

To apply magic effects, you must create a new class that is inherited from the widget to which you apply the effect and from the MagicBehavior class.

In KV file:

<MagicButton@MagicBehavior+MDRectangleFlatButton>

In python file:

class MagicButton(MagicBehavior, MDRectangleFlatButton):
    pass

The MagicBehavior class provides five effects:

Example:

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<MagicButton@MagicBehavior+MDRectangleFlatButton>


MDFloatLayout:

    MagicButton:
        text: "WOBBLE EFFECT"
        on_release: self.wobble()
        pos_hint: {"center_x": .5, "center_y": .3}

    MagicButton:
        text: "GROW EFFECT"
        on_release: self.grow()
        pos_hint: {"center_x": .5, "center_y": .4}

    MagicButton:
        text: "SHAKE EFFECT"
        on_release: self.shake()
        pos_hint: {"center_x": .5, "center_y": .5}

    MagicButton:
        text: "TWIST EFFECT"
        on_release: self.twist()
        pos_hint: {"center_x": .5, "center_y": .6}

    MagicButton:
        text: "SHRINK EFFECT"
        on_release: self.shrink()
        pos_hint: {"center_x": .5, "center_y": .7}
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/magic-button.gif
API - kivymd.uix.behaviors.magic_behavior#
class kivymd.uix.behaviors.magic_behavior.MagicBehavior#
magic_speed#

Animation playback speed.

magic_speed is a NumericProperty and defaults to 1.

grow() None#

Grow effect animation.

shake() None#

Shake effect animation.

wobble() None#

Wobble effect animation.

twist() None#

Twist effect animation.

shrink() None#

Shrink effect animation.

on_touch_up(*args)#

Rotate#

#

New in version 1.1.0.

Base class for controlling the rotate of the widget.

Note

See kivy.graphics.Rotate for more information.

Kivy#
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.app import App
from kivy.properties import NumericProperty
from kivy.uix.button import Button

KV = '''
Screen:

    RotateButton:
        size_hint: .5, .5
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.change_rotate(self)

        canvas.before:
            PushMatrix
            Rotate:
                angle: self.rotate_value_angle
                axis: 0, 0, 1
                origin: self.center
        canvas.after:
            PopMatrix
'''


class RotateButton(Button):
    rotate_value_angle = NumericProperty(0)


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

    def change_rotate(self, instance_button: Button) -> None:
        Animation(rotate_value_angle=45, d=0.3).start(instance_button)


Test().run()
KivyMD#
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import RotateBehavior
from kivymd.uix.boxlayout import MDBoxLayout

KV = '''
MDScreen:

    RotateBox:
        size_hint: .5, .5
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.change_rotate(self)
        md_bg_color: "red"
'''


class RotateBox(ButtonBehavior, RotateBehavior, MDBoxLayout):
    pass


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

    def change_rotate(self, instance_button: RotateBox) -> None:
        Animation(rotate_value_angle=45, d=0.3).start(instance_button)


Test().run()

Warning

Do not use RotateBehavior class with classes that inherited` from CommonElevationBehavior class. CommonElevationBehavior classes by default contains attributes for rotate widget.

API - kivymd.uix.behaviors.rotate_behavior#
class kivymd.uix.behaviors.rotate_behavior.RotateBehavior#

Base class for controlling the rotate of the widget.

rotate_value_angle#

Property for getting/setting the angle of the rotation.

rotate_value_angle is an NumericProperty and defaults to 0.

rotate_value_axis#

Property for getting/setting the axis of the rotation.

rotate_value_axis is an ListProperty and defaults to (0, 0, 1).

Scale#

#

New in version 1.1.0.

Base class for controlling the scale of the widget.

Note

See kivy.graphics.Rotate for more information.

Kivy#
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.properties import NumericProperty
from kivy.uix.button import Button
from kivy.app import App


KV = '''
Screen:

    ScaleButton:
        size_hint: .5, .5
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.change_scale(self)

        canvas.before:
            PushMatrix
            Scale:
                x: self.scale_value_x
                y: self.scale_value_y
                z: self.scale_value_x
                origin: self.center
        canvas.after:
            PopMatrix
'''


class ScaleButton(Button):
    scale_value_x = NumericProperty(1)
    scale_value_y = NumericProperty(1)
    scale_value_z = NumericProperty(1)


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

    def change_scale(self, instance_button: Button) -> None:
        Animation(
            scale_value_x=0.5,
            scale_value_y=0.5,
            scale_value_z=0.5,
            d=0.3,
        ).start(instance_button)


Test().run()
KivyMD#
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import ScaleBehavior
from kivymd.uix.boxlayout import MDBoxLayout

KV = '''
MDScreen:

    ScaleBox:
        size_hint: .5, .5
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.change_scale(self)
        md_bg_color: "red"
'''


class ScaleBox(ButtonBehavior, ScaleBehavior, MDBoxLayout):
    pass


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

    def change_scale(self, instance_button: ScaleBox) -> None:
        Animation(
            scale_value_x=0.5,
            scale_value_y=0.5,
            scale_value_z=0.5,
            d=0.3,
        ).start(instance_button)


Test().run()

Warning

Do not use ScaleBehavior class with classes that inherited` from CommonElevationBehavior class. CommonElevationBehavior classes by default contains attributes for scale widget.

API - kivymd.uix.behaviors.scale_behavior#
class kivymd.uix.behaviors.scale_behavior.ScaleBehavior#

Base class for controlling the scale of the widget.

scale_value_x#

X-axis value.

scale_value_x is an NumericProperty and defaults to 1.

scale_value_y#

Y-axis value.

scale_value_y is an NumericProperty and defaults to 1.

scale_value_z#

Z-axis value.

scale_value_z is an NumericProperty and defaults to 1.

scale_value_center#

Origin of the scale.

New in version 1.2.0.

The format of the origin can be either (x, y) or (x, y, z).

scale_value_center is an NumericProperty and defaults to [].

ToggleButton#

#

This behavior must always be inherited after the button’s Widget class since it works with the inherited properties of the button class.

example:

class MyToggleButtonWidget(MDFlatButton, MDToggleButton):
    # [...]
    pass
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors.toggle_behavior import MDToggleButton
from kivymd.uix.button import MDFlatButton

KV = '''
MDScreen:

    MDBoxLayout:
        adaptive_size: True
        spacing: "12dp"
        pos_hint: {"center_x": .5, "center_y": .5}

        MyToggleButton:
            text: "Show ads"
            group: "x"

        MyToggleButton:
            text: "Do not show ads"
            group: "x"

        MyToggleButton:
            text: "Does not matter"
            group: "x"
'''


class MyToggleButton(MDFlatButton, MDToggleButton):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.background_down = self.theme_cls.primary_color


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


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toggle-button-1.gif
You can inherit the MyToggleButton class only from the following classes#
  • MDRaisedButton

  • MDFlatButton

  • MDRectangleFlatButton

  • MDRectangleFlatIconButton

  • MDRoundFlatButton

  • MDRoundFlatIconButton

  • MDFillRoundFlatButton

  • MDFillRoundFlatIconButton

API - kivymd.uix.behaviors.toggle_behavior#
class kivymd.uix.behaviors.toggle_behavior.MDToggleButtonBehavior(**kwargs)#

This mixin class provides togglebutton behavior. Please see the togglebutton behaviors module documentation for more information.

New in version 1.8.0.

background_normal#

Color of the button in rgba format for the ‘normal’ state.

background_normal is a ColorProperty and is defaults to None.

background_down#

Color of the button in rgba format for the ‘down’ state.

background_down is a ColorProperty and is defaults to None.

font_color_normal#

Color of the font’s button in rgba format for the ‘normal’ state.

font_color_normal is a ColorProperty and is defaults to None.

font_color_down#

Color of the font’s button in rgba format for the ‘down’ state.

font_color_down is a ColorProperty and is defaults to [1, 1, 1, 1].

Hover#

#

Changing when the mouse is on the widget and the widget is visible.

To apply hover behavior, you must create a new class that is inherited from the widget to which you apply the behavior and from the HoverBehavior class.

In KV file:

<HoverItem@MDBoxLayout+HoverBehavior>

In python file:

class HoverItem(MDBoxLayout, HoverBehavior):
    '''Custom item implementing hover behavior.'''

After creating a class, you must define two methods for it: HoverBehavior.on_enter and HoverBehavior.on_leave, which will be automatically called when the mouse cursor is over the widget and when the mouse cursor goes beyond the widget.

Note

HoverBehavior will by default check to see if the current Widget is visible (i.e. not covered by a modal or popup and not a part of a RelativeLayout, MDTab or Carousel that is not currently visible etc) and will only issue events if the widget is visible.

To get the legacy behavior that the events are always triggered, you can set detect_visible on the Widget to False.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import HoverBehavior
from kivymd.uix.boxlayout import MDBoxLayout

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

    MDBoxLayout:
        id: box
        pos_hint: {'center_x': .5, 'center_y': .5}
        size_hint: .8, .8
        md_bg_color: self.theme_cls.secondaryContainerColor
'''


class HoverItem(MDBoxLayout, HoverBehavior):
    '''Custom item implementing hover behavior.'''

    def on_enter(self, *args):
        '''
        The method will be called when the mouse cursor
        is within the borders of the current widget.
        '''

        self.md_bg_color = "white"

    def on_leave(self, *args):
        '''
        The method will be called when the mouse cursor goes beyond
        the borders of the current widget.
        '''

        self.md_bg_color = self.theme_cls.secondaryContainerColor


class Example(MDApp):
    def build(self):
        self.screen = Builder.load_string(KV)
        for i in range(5):
            self.screen.ids.box.add_widget(HoverItem())
        return self.screen


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hover-behavior.gif
API - kivymd.uix.behaviors.hover_behavior#
class kivymd.uix.behaviors.hover_behavior.HoverBehavior(*args, **kwargs)#
Events:
on_enter

Fired when mouse enters the bbox of the widget and the widget is visible.

on_leave

Fired when the mouse exits the widget and the widget is visible.

hovering#

True, if the mouse cursor is within the borders of the widget.

Note that this is set and cleared even if the widget is not visible.

hover is a BooleanProperty and defaults to False.

hover_visible#

True if hovering is True and is the current widget is visible.

hover_visible is a BooleanProperty and defaults to False.

enter_point#

Holds the last position where the mouse pointer crossed into the Widget if the Widget is visible and is currently in a hovering state.

enter_point is a ObjectProperty and defaults to None.

detect_visible#

Should this widget perform the visibility check?

detect_visible is a BooleanProperty and defaults to True.

on_mouse_update(*args)#
on_enter()#

Fired when mouse enter the bbox of the widget.

on_leave()#

Fired when the mouse goes outside the widget border.

Background Color#

#

Note

The following classes are intended for in-house use of the library.

API - kivymd.uix.behaviors.backgroundcolor_behavior#
class kivymd.uix.behaviors.backgroundcolor_behavior.BackgroundColorBehavior(**kwarg)#
background#

Background image path.

background is a StringProperty and defaults to ‘’.

radius#

Canvas radius.

# Top left corner slice.
MDBoxLayout:
    md_bg_color: app.theme_cls.primary_color
    radius: [25, 0, 0, 0]

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

md_bg_color#

The background color of the widget (Widget) that will be inherited from the BackgroundColorBehavior class.

For example:

Widget:
    canvas:
        Color:
            rgba: 0, 1, 1, 1
        Rectangle:
            size: self.size
            pos: self.pos

similar to code:

<MyWidget@BackgroundColorBehavior>
    md_bg_color: 0, 1, 1, 1

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

line_color#

If a custom value is specified for the line_color parameter, the border of the specified color will be used to border the widget:

MDBoxLayout:
    size_hint: .5, .2
    md_bg_color: 0, 1, 1, .5
    line_color: 0, 0, 1, 1
    radius: [24, ]

New in version 0.104.2.

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

line_width#

Border of the specified width will be used to border the widget.

New in version 1.0.0.

line_width is an NumericProperty and defaults to 1.

angle#
background_origin#
on_md_bg_color(instance, color: list | str)#

Fired when the values of md_bg_color change.

update_background_origin(instance, pos: list) None#

Fired when the values of pos change.

Elevation#

#

Elevation is the relative distance between two surfaces along the z-axis.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/elevation-previous.png

To create an elevation effect, use the CommonElevationBehavior class. For example, let’s create a button with a rectangular elevation effect:

from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import (
    RectangularRippleBehavior,
    BackgroundColorBehavior,
    CommonElevationBehavior,
)

KV = '''
<ElevationWidget>
    size_hint: None, None
    size: "250dp", "50dp"


MDScreen:

    # With elevation effect
    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 4
        shadow_offset: 0, -6
        shadow_softness: 4

    # Without elevation effect
    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .4}
'''


class ElevationWidget(
    RectangularRippleBehavior,
    CommonElevationBehavior,
    ButtonBehavior,
    BackgroundColorBehavior,
):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.md_bg_color = "red"


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-elevation-effect.png

Warning

If before the KivyMD 1.1.0 library version you used the elevation property with an average value of 12 for the shadow, then starting with the KivyMD 1.1.0 library version, the average value of the elevation property will be somewhere 4.

Similarly, create a circular button:

from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import CircularRippleBehavior, CommonElevationBehavior
from kivymd.uix.floatlayout import MDFloatLayout

KV = '''
<CircularElevationButton>
    size_hint: None, None
    size: "100dp", "100dp"
    radius: self.size[0] / 2
    shadow_radius: self.radius[0]
    md_bg_color: "red"

    MDIcon:
        icon: "hand-heart"
        halign: "center"
        valign: "center"
        pos_hint: {"center_x": .5, "center_y": .5}
        size: root.size
        pos: root.pos
        font_size: root.size[0] * .6
        theme_text_color: "Custom"
        text_color: "white"


MDScreen:

    CircularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 4
        shadow_softness: 4
'''


class CircularElevationButton(
    CommonElevationBehavior,
    CircularRippleBehavior,
    ButtonBehavior,
    MDFloatLayout,
):
    pass


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/circular-elevation-effect.png
Animating the elevation#
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior, RectangularRippleBehavior
from kivymd.uix.widget import MDWidget

KV = '''
MDScreen:

    ElevatedWidget:
        pos_hint: {'center_x': .5, 'center_y': .5}
        size_hint: None, None
        size: 100, 100
        md_bg_color: 0, 0, 1, 1
        elevation: 2
        radius: dp(18)
'''


class ElevatedWidget(
    CommonElevationBehavior,
    RectangularRippleBehavior,
    ButtonBehavior,
    MDWidget,
):
    _elev = 0  # previous elevation value

    def on_press(self, *args):
        if not self._elev:
            self._elev = self.elevation
        Animation(elevation=self.elevation + 2, d=0.4).start(self)

    def on_release(self, *args):
        Animation.cancel_all(self, "elevation")
        Animation(elevation=self._elev, d=0.1).start(self)


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-elevation-animation-effect.gif
API - kivymd.uix.behaviors.elevation#
class kivymd.uix.behaviors.elevation.CommonElevationBehavior(**kwargs)#

Common base class for rectangular and circular elevation behavior.

For more information, see in the Widget class documentation.

elevation_level#

Elevation level (values from 0 to 5)

New in version 1.2.0.

elevation_level is an BoundedNumericProperty and defaults to 0.

elevation_levels#

Elevation is measured as the distance between components along the z-axis in density-independent pixels (dps).

New in version 1.2.0.

elevation_levels is an DictProperty and defaults to {0: dp(0), 1: dp(8), 2: dp(23), 3: dp(16), 4: dp(20), 5: dp(24)}.

elevation#

Elevation of the widget.

elevation is an BoundedNumericProperty and defaults to 0.

shadow_radius#

Radius of the corners of the shadow.

New in version 1.1.0.

You don’t have to use this parameter. The radius of the elevation effect is calculated automatically one way or another based on the radius of the parent widget, for example:

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDCard:
        radius: dp(12), dp(46), dp(12), dp(46)
        size_hint: .5, .3
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 2
        shadow_softness: 4
        shadow_offset: (2, -2)
'''


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


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

shadow_radius is an VariableListProperty and defaults to [0, 0, 0, 0].

shadow_softness#

Softness of the shadow.

New in version 1.1.0.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import BackgroundColorBehavior, CommonElevationBehavior

KV = '''
<ElevationWidget>
    size_hint: None, None
    size: "250dp", "50dp"


MDScreen:

    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 6
        shadow_softness: 6

    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .4}
        elevation: 6
        shadow_softness: 12
'''


class ElevationWidget(CommonElevationBehavior, BackgroundColorBehavior):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.md_bg_color = "blue"


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-softness.png

shadow_softness is an NumericProperty and defaults to 0.0.

shadow_offset#

Offset of the shadow.

New in version 1.1.0.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import BackgroundColorBehavior, CommonElevationBehavior

KV = '''
<ElevationWidget>
    size_hint: None, None
    size: "100dp", "100dp"


MDScreen:

    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 6
        shadow_radius: dp(6)
        shadow_softness: 12
        shadow_offset: -12, -12
'''


class ElevationWidget(CommonElevationBehavior, BackgroundColorBehavior):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.md_bg_color = "blue"


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-1.png
ElevationWidget:
    shadow_offset: 12, -12
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-2.png
ElevationWidget:
    shadow_offset: 12, 12
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-3.png
ElevationWidget:
    shadow_offset: -12, 12
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-4.png

shadow_offset is an ListProperty and defaults to (0, 0).

shadow_color#

Offset of the shadow.

New in version 1.1.0.

ElevationWidget:
    shadow_color: 0, 0, 1, .8
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-color.png

shadow_color is an ColorProperty and defaults to [0, 0, 0, 0.6].

scale_value_x#

X-axis value.

New in version 1.2.0.

scale_value_x is an NumericProperty and defaults to 1.

scale_value_y#

Y-axis value.

New in version 1.2.0.

scale_value_y is an NumericProperty and defaults to 1.

scale_value_z#

Z-axis value.

New in version 1.2.0.

scale_value_z is an NumericProperty and defaults to 1.

scale_value_center#

Origin of the scale.

New in version 1.2.0.

The format of the origin can be either (x, y) or (x, y, z).

scale_value_center is an NumericProperty and defaults to [].

rotate_value_angle#

Property for getting/setting the angle of the rotation.

New in version 1.2.0.

rotate_value_angle is an NumericProperty and defaults to 0.

rotate_value_axis#

Property for getting/setting the axis of the rotation.

New in version 1.2.0.

rotate_value_axis is an ListProperty and defaults to (0, 0, 1).

State Layer#

#
API - kivymd.uix.behaviors.state_layer_behavior#
class kivymd.uix.behaviors.state_layer_behavior.StateLayerBehavior(*args, **kwargs)#

Focus behavior class.

For more information, see in the HoverBehavior and ButtonBehavior classes documentation.

Events:
on_enter

Fired when mouse enters the bbox of the widget AND the widget is visible.

on_leave

Fired when the mouse exits the widget AND the widget is visible.

state_layer_color#

The color of the layer state.

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

state_hover#

The transparency level of the layer as a percentage when hovering.

state_hover is an NumericProperty and defaults to 0.08.

state_press#

The transparency level of the layer as a percentage when pressed.

state_press is an NumericProperty and defaults to 0.12.

state_drag#

The transparency level of the layer as a percentage when dragged.

state_drag is an NumericProperty and defaults to 0.16.

icon_button_filled_opacity_value_disabled_container#
icon_button_filled_opacity_value_disabled_icon#
icon_button_tonal_opacity_value_disabled_container#
icon_button_tonal_opacity_value_disabled_icon#
icon_button_outlined_opacity_value_disabled_container#
icon_button_outlined_opacity_value_disabled_line#
icon_button_outlined_opacity_value_disabled_icon#
icon_button_standard_opacity_value_disabled_icon#
fab_button_opacity_value_disabled_container#
fab_button_opacity_value_disabled_icon#
button_filled_opacity_value_disabled_container#
button_filled_opacity_value_disabled_icon#
button_filled_opacity_value_disabled_text#
button_tonal_opacity_value_disabled_container#
button_tonal_opacity_value_disabled_icon#
button_tonal_opacity_value_disabled_text#
button_outlined_opacity_value_disabled_container#
button_outlined_opacity_value_disabled_line#
button_outlined_opacity_value_disabled_icon#
button_outlined_opacity_value_disabled_text#
button_elevated_opacity_value_disabled_container#
button_elevated_opacity_value_disabled_icon#
button_elevated_opacity_value_disabled_text#
button_text_opacity_value_disabled_icon#
button_text_opacity_value_disabled_text#
label_opacity_value_disabled_text#
card_filled_opacity_value_disabled_state_container#
card_outlined_opacity_value_disabled_state_container#
card_opacity_value_disabled_state_elevated_container#
segmented_button_opacity_value_disabled_container#
segmented_button_opacity_value_disabled_container_active#
segmented_button_opacity_value_disabled_line#
segmented_button_opacity_value_disabled_icon#
segmented_button_opacity_value_disabled_text#
chip_opacity_value_disabled_container#
chip_opacity_value_disabled_text#
chip_opacity_value_disabled_icon#
switch_opacity_value_disabled_line#
switch_opacity_value_disabled_container#
switch_thumb_opacity_value_disabled_container#
switch_opacity_value_disabled_icon#
checkbox_opacity_value_disabled_container#
list_opacity_value_disabled_container#
list_opacity_value_disabled_leading_avatar#
text_field_filled_opacity_value_disabled_state_container#
text_field_outlined_opacity_value_disabled_state_container#
text_field_opacity_value_disabled_max_length_label#
text_field_opacity_value_disabled_helper_text_label#
text_field_opacity_value_disabled_hint_text_label#
text_field_opacity_value_disabled_leading_icon#
text_field_opacity_value_disabled_trailing_icon#
text_field_opacity_value_disabled_line#
set_properties_widget() None#

Fired on_release/on_press/on_enter/on_leave events.

on_disabled(instance, value) None#

Fired when the disabled value changes.

on_enter() None#

Fired when mouse enter the bbox of the widget.

on_leave() None#

Fired when the mouse goes outside the widget border.

Declarative#

#

New in version 1.0.0.

As you already know, the Kivy framework provides the best/simplest/modern UI creation tool that allows you to separate the logic of your application from the description of the properties of widgets/GUI components. This tool is named KV Language.

But in addition to creating a user interface using the KV Language Kivy allows you to create user interface elements directly in the Python code. And if you’ve ever created a user interface in Python code, you know how ugly it looks. Even in the simplest user interface design, which was created using Python code it is impossible to trace the widget tree, because in Python code you build the user interface in an imperative style.

Imperative style#
from kivymd.app import MDApp
from kivymd.uix.navigationbar import (
    MDNavigationBar,
    MDNavigationItem,
    MDNavigationItemIcon,
    MDNavigationItemLabel,
)
from kivymd.uix.screen import MDScreen


class Example(MDApp):
    def build(self):
        screen = MDScreen()
        bottom_navigation = MDNavigationBar()

        datas = [
            {"text": "Mail", "icon": "gmail"},
            {"text": "GitHub", "icon": "git"},
            {"text": "LinkedIN", "icon": "linkedin"},
        ]
        for data in datas:
            text = data["text"]
            navigation_item = MDNavigationItem(
                MDNavigationItemIcon(
                    icon=data["icon"],
                ),
                MDNavigationItemLabel(
                    text=text,
                ),
            )
            bottom_navigation.add_widget(navigation_item)

        screen.add_widget(bottom_navigation)
        return screen


Example().run()

Take a look at the above code example. This is a very simple UI. But looking at this code, you will not be able to figure the widget tree and understand which UI this code implements. This is named imperative programming style, which is used in Kivy.

Now let’s see how the same code is implemented using the KV language, which uses a declarative style of describing widget properties.

Declarative style with KV language#
from kivy.lang import Builder

from kivymd.app import MDApp


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

    MDNavigationBar:

        MDNavigationItem:

            MDNavigationItemIcon:
                icon: "gmail"

            MDNavigationItemLabel:
                text: "Mail"

        MDNavigationItem:

            MDNavigationItemIcon:
                icon: "git"

            MDNavigationItemLabel:
                text: "GitHub"

        MDNavigationItem:

            MDNavigationItemIcon:
                icon: "linkedin"

            MDNavigationItemLabel:
                text: "LinkedIN"
'''
        )


Example().run()

Looking at this code, we can now clearly see the widget tree and their properties. We can quickly navigate through the components of the screen and quickly change/add new properties/widgets. This is named declarative UI creation style.

But now the KivyMD library allows you to write Python code in a declarative style. Just as it is implemented in Flutter/Jetpack Compose/SwiftUI.

Declarative style with Python code#
from kivymd.app import MDApp
from kivymd.uix.navigationbar import (
    MDNavigationBar,
    MDNavigationItemIcon,
    MDNavigationItem,
    MDNavigationItemLabel,
)


class Example(MDApp):
    def build(self):
        return MDNavigationBar(
            MDNavigationItem(
                MDNavigationItemIcon(
                    icon="gmail",
                ),
                MDNavigationItemLabel(
                    text="Mail",
                ),
            ),
            MDNavigationItem(
                MDNavigationItemIcon(
                    icon="twitter",
                ),
                MDNavigationItemLabel(
                    text="Twitter",
                ),
            ),
            MDNavigationItem(
                MDNavigationItemIcon(
                    icon="linkedin",
                ),
                MDNavigationItemLabel(
                    text="LinkedIN",
                ),
            ),
        )


Example().run()

Note

The KivyMD library does not support creating Kivy widgets in Python code in a declarative style.

But you can still use the declarative style of creating Kivy widgets in Python code. To do this, you need to create a new class that will be inherited from the Kivy widget and the DeclarativeBehavior class:

from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button

from kivymd.app import MDApp
from kivymd.uix.behaviors import DeclarativeBehavior


class DeclarativeStyleBoxLayout(DeclarativeBehavior, BoxLayout):
    pass


class Example(MDApp):
    def build(self):
        return (
            DeclarativeStyleBoxLayout(
                Button(),
                Button(),
                orientation="vertical",
            )
        )


Example().run()
Get objects by identifiers#

In the declarative style in Python code, the ids parameter of the specified widget will return only the id of the child widget/container, ignoring other ids. Therefore, to get objects by identifiers in declarative style in Python code, you must specify all the container ids in which the widget is nested until you get to the desired id:

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.floatlayout import MDFloatLayout


class Example(MDApp):
    def build(self):
        return (
            MDBoxLayout(
                MDFloatLayout(
                    MDButton(
                        MDButtonText(
                            text="Button 1",
                        ),
                        id="button_1",
                        pos_hint={"center_x": 0.5, "center_y": 0.5},
                    ),
                    id="box_container_1",
                ),
                MDBoxLayout(
                    MDFloatLayout(
                        MDButton(
                            MDButtonText(
                                text="Button 2",
                            ),
                            id="button_2",
                            pos_hint={"center_x": 0.5, "center_y": 0.5},
                        ),
                        id="float_container",
                    ),
                    id="box_container_2",
                )
            )
        )

    def on_start(self):
        # {
        #     'button_1': <kivymd.uix.button.button.MDButton object at 0x11d93c9e0>,
        #     'button_2': <kivymd.uix.button.button.MDButton object at 0x11da128f0>,
        #     'float_container': <kivymd.uix.floatlayout.MDFloatLayout object at 0x11da228f0>,
        #     'box_container_1': <kivymd.uix.floatlayout.MDFloatLayout object at 0x11d9fc3c0>,
        #     'box_container_2': <kivymd.uix.boxlayout.MDBoxLayout object at 0x11dbf06d0>,
        # }
        super().on_start()
        print(self.root.get_ids())


Example().run()

Yes, this is not a very good solution, but I think it will be fixed soon.

Warning

Declarative programming style in Python code in the KivyMD library is an experimental feature. Therefore, if you receive errors, do not hesitate to create new issue in the KivyMD repository.

API - kivymd.uix.behaviors.declarative_behavior#
class kivymd.uix.behaviors.declarative_behavior.DeclarativeBehavior(*args, **kwargs)#

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

id#

Widget ID.

id is an StringProperty and defaults to ‘’.

get_ids() dict#

Returns a dictionary of widget IDs defined in Python code that is written in a declarative style.

Ripple#

#

Classes implements a circular and rectangular ripple effects.

To create a widget with сircular ripple effect, you must create a new class that inherits from the CircularRippleBehavior class.

For example, let’s create an image button with a circular ripple effect:

from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior
from kivy.uix.image import Image

from kivymd.app import MDApp
from kivymd.uix.behaviors import CircularRippleBehavior

KV = '''
MDScreen:

    CircularRippleButton:
        source: "data/logo/kivy-icon-256.png"
        size_hint: None, None
        size: "250dp", "250dp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class CircularRippleButton(CircularRippleBehavior, ButtonBehavior, Image):
    def __init__(self, **kwargs):
        self.ripple_scale = 0.85
        super().__init__(**kwargs)


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/circular-ripple-effect.gif

To create a widget with rectangular ripple effect, you must create a new class that inherits from the RectangularRippleBehavior class:

from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import RectangularRippleBehavior, BackgroundColorBehavior

KV = '''
MDScreen:

    RectangularRippleButton:
        size_hint: None, None
        size: "250dp", "50dp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class RectangularRippleButton(
    RectangularRippleBehavior, ButtonBehavior, BackgroundColorBehavior
):
    md_bg_color = [0, 0, 1, 1]


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-ripple-effect.gif
API - kivymd.uix.behaviors.ripple_behavior#
class kivymd.uix.behaviors.ripple_behavior.CommonRipple#

Base class for ripple effect.

ripple_rad_default#

The starting value of the radius of the ripple effect.

CircularRippleButton:
    ripple_rad_default: 100
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-rad-default.gif

ripple_rad_default is an NumericProperty and defaults to 1.

ripple_color#

Ripple color in (r, g, b, a) format.

CircularRippleButton:
    ripple_color: app.theme_cls.primary_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-color.gif

ripple_color is an ColorProperty and defaults to None.

ripple_alpha#

Alpha channel values for ripple effect.

CircularRippleButton:
    ripple_alpha: .9
    ripple_color: app.theme_cls.primary_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-alpha.gif

ripple_alpha is an NumericProperty and defaults to 0.5.

ripple_scale#

Ripple effect scale.

CircularRippleButton:
    ripple_scale: .5
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-scale-05.gif
CircularRippleButton:
    ripple_scale: 1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-scale-1.gif

ripple_scale is an NumericProperty and defaults to None.

ripple_duration_in_fast#

Ripple duration when touching to widget.

CircularRippleButton:
    ripple_duration_in_fast: .1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-duration-in-fast.gif

ripple_duration_in_fast is an NumericProperty and defaults to 0.3.

ripple_duration_in_slow#

Ripple duration when long touching to widget.

CircularRippleButton:
    ripple_duration_in_slow: 5
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-duration-in-slow.gif

ripple_duration_in_slow is an NumericProperty and defaults to 2.

ripple_duration_out#

The duration of the disappearance of the wave effect.

CircularRippleButton:
    ripple_duration_out: 5
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-duration-out.gif

ripple_duration_out is an NumericProperty and defaults to 0.3.

ripple_canvas_after#

The ripple effect is drawn above/below the content.

New in version 1.0.0.

MDIconButton:
    ripple_canvas_after: True
    icon: "android"
    ripple_alpha: .8
    ripple_color: app.theme_cls.primary_color
    icon_size: "100sp"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-canvas-after-true.gif
MDIconButton:
    ripple_canvas_after: False
    icon: "android"
    ripple_alpha: .8
    ripple_color: app.theme_cls.primary_color
    icon_size: "100sp"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/ripple-canvas-after-false.gif

ripple_canvas_after is an BooleanProperty and defaults to True.

ripple_func_in#

Type of animation for ripple in effect.

ripple_func_in is an StringProperty and defaults to ‘out_quad’.

ripple_func_out#

Type of animation for ripple out effect.

ripple_func_out is an StringProperty and defaults to ‘ripple_func_out’.

ripple_effect#

Should I use the ripple effect.

ripple_effect is an BooleanProperty and defaults to True.

abstract lay_canvas_instructions() NoReturn#
start_ripple() None#
finish_ripple() None#
fade_out(*args) None#
anim_complete(*args) None#

Fired when the “fade_out” animation complete.

on_touch_down(touch)#
call_ripple_animation_methods(touch) None#
on_touch_move(touch, *args)#
on_touch_up(touch)#
class kivymd.uix.behaviors.ripple_behavior.RectangularRippleBehavior#

Class implements a rectangular ripple effect.

For more information, see in the CommonRipple class documentation.

ripple_scale#

See ripple_scale.

ripple_scale is an NumericProperty and defaults to 2.75.

lay_canvas_instructions() None#

Adds graphic instructions to the canvas to implement ripple animation.

class kivymd.uix.behaviors.ripple_behavior.CircularRippleBehavior#

Class implements a circular ripple effect.

For more information, see in the CommonRipple class documentation.

ripple_scale#

See ripple_scale.

ripple_scale is an NumericProperty and defaults to 1.

lay_canvas_instructions() None#

Touch#

#

Provides easy access to events.

The following events are available:

  • on_long_touch

  • on_double_tap

  • on_triple_tap

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

from kivymd.app import MDApp
from kivymd.uix.behaviors import TouchBehavior
from kivymd.uix.button import MDButton

KV = '''
<TouchBehaviorButton>
    style: "elevated"

    MDButtonText:
        text: root.text


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    TouchBehaviorButton:
        text: "TouchBehavior"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class TouchBehaviorButton(MDButton, TouchBehavior):
    text = StringProperty()

    def on_long_touch(self, *args):
        print("<on_long_touch> event")

    def on_double_tap(self, *args):
        print("<on_double_tap> event")

    def on_triple_tap(self, *args):
        print("<on_triple_tap> event")


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


Example().run()
API - kivymd.uix.behaviors.touch_behavior#
class kivymd.uix.behaviors.touch_behavior.TouchBehavior(**kwargs)#
duration_long_touch#

Time for a long touch.

duration_long_touch is an NumericProperty and defaults to 0.4.

create_clock(widget, touch, *args)#
delete_clock(widget, touch, *args)#

Removes a key event from touch.ud.

on_long_touch(touch, *args)#

Fired when the widget is pressed for a long time.

on_double_tap(touch, *args)#

Fired by double-clicking on the widget.

on_triple_tap(touch, *args)#

Fired by triple clicking on the widget.

Stencil#

#

New in version 1.1.0.

Base class for controlling the stencil instructions of the widget.

Note

See Stencil instructions for more information.

Kivy#
from kivy.lang import Builder
from kivy.app import App

KV = '''
Carousel:

    Button:
        size_hint: .9, .8
        pos_hint: {"center_x": .5, "center_y": .5}

        canvas.before:
            StencilPush
            RoundedRectangle:
                pos: root.pos
                size: root.size
            StencilUse
        canvas.after:
            StencilUnUse
            RoundedRectangle:
                pos: root.pos
                size: root.size
            StencilPop
'''


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


Test().run()
KivyMD#
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import StencilBehavior
from kivymd.uix.fitimage import FitImage

KV = '''
#:import os os
#:import images_path kivymd.images_path


Carousel:

    StencilImage:
        size_hint: .9, .8
        pos_hint: {"center_x": .5, "center_y": .5}
        source: os.path.join(images_path, "logo", "kivymd-icon-512.png")
'''


class StencilImage(FitImage, StencilBehavior):
    pass


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


Test().run()
API - kivymd.uix.behaviors.stencil_behavior#
class kivymd.uix.behaviors.stencil_behavior.StencilBehavior#

Base class for controlling the stencil instructions of the widget.

radius#

Canvas radius.

New in version 1.0.0.

# Top left corner slice.
MDWidget:
    radius: [25, 0, 0, 0]

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

Focus#

#

Changing the background color when the mouse is on the widget.

To apply focus behavior, you must create a new class that is inherited from the widget to which you apply the behavior and from the FocusBehavior class.

Usage#
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.behaviors.focus_behavior import FocusBehavior

KV = '''
MDScreen:
    md_bg_color: 1, 1, 1, 1

    FocusWidget:
        size_hint: .5, .3
        pos_hint: {"center_x": .5, "center_y": .5}
        md_bg_color: app.theme_cls.bg_light

        MDLabel:
            text: "Label"
            theme_text_color: "Primary"
            pos_hint: {"center_y": .5}
            halign: "center"
'''


class FocusWidget(MDBoxLayout, CommonElevationBehavior, FocusBehavior):
    pass


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


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

Color change at focus/defocus

FocusWidget:
    focus_color: 1, 0, 1, 1
    unfocus_color: 0, 0, 1, 1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/focus-defocus-color.gif
API - kivymd.uix.behaviors.focus_behavior#
class kivymd.uix.behaviors.focus_behavior.FocusBehavior(*args, **kwargs)#

Focus behavior class.

For more information, see in the HoverBehavior and ButtonBehavior classes documentation.

Events:
on_enter

Fired when mouse enters the bbox of the widget AND the widget is visible.

on_leave

Fired when the mouse exits the widget AND the widget is visible.

focus_behavior#

Using focus when hovering over a widget.

focus_behavior is a BooleanProperty and defaults to False.

focus_color#

The color of the widget when the mouse enters the bbox of the widget.

focus_color is a ColorProperty and defaults to None.

unfocus_color#

The color of the widget when the mouse exits the bbox widget.

unfocus_color is a ColorProperty and defaults to None.

Effects#

StiffScrollEffect#

#

An Effect to be used with ScrollView to prevent scrolling beyond the bounds, but politely.

A ScrollView constructed with StiffScrollEffect, eg. ScrollView(effect_cls=StiffScrollEffect), will get harder to scroll as you get nearer to its edges. You can scroll all the way to the edge if you want to, but it will take more finger-movement than usual.

Unlike DampedScrollEffect, it is impossible to overscroll with StiffScrollEffect. That means you cannot push the contents of the ScrollView far enough to see what’s beneath them. This is appropriate if the ScrollView contains, eg., a background image, like a desktop wallpaper. Overscrolling may give the impression that there is some reason to overscroll, even if just to take a peek beneath, and that impression may be misleading.

StiffScrollEffect was written by Zachary Spector. His other stuff is at: https://github.com/LogicalDash/ He can be reached, and possibly hired, at: zacharyspector@gmail.com

API - kivymd.effects.stiffscroll.stiffscroll#
class kivymd.effects.stiffscroll.stiffscroll.StiffScrollEffect(**kwargs)#

Kinetic effect class. See module documentation for more information.

drag_threshold#

Minimum distance to travel before the movement is considered as a drag.

drag_threshold is an NumericProperty and defaults to ’20sp’.

min#

Minimum boundary to stop the scrolling at.

min is an NumericProperty and defaults to 0.

max#

Maximum boundary to stop the scrolling at.

max is an NumericProperty and defaults to 0.

max_friction#

How hard should it be to scroll, at the worst?

max_friction is an NumericProperty and defaults to 1.

body#

Proportion of the range in which you can scroll unimpeded.

body is an NumericProperty and defaults to 0.7.

scroll#

Computed value for scrolling

scroll is an NumericProperty and defaults to 0.0.

transition_min#

The AnimationTransition function to use when adjusting the friction near the minimum end of the effect.

transition_min is an ObjectProperty and defaults to kivy.animation.AnimationTransition.

transition_max#

The AnimationTransition function to use when adjusting the friction near the maximum end of the effect.

transition_max is an ObjectProperty and defaults to kivy.animation.AnimationTransition.

target_widget#

The widget to apply the effect to.

target_widget is an ObjectProperty and defaults to None.

displacement#

The absolute distance moved in either direction.

displacement is an NumericProperty and defaults to 0.

update_velocity(dt)#

Before actually updating my velocity, meddle with self.friction to make it appropriate to where I’m at, currently.

on_value(*args)#

Prevent moving beyond my bounds, and update self.scroll

start(val, t=None)#

Start movement with self.friction = self.base_friction

update(val, t=None)#

Reduce the impact of whatever change has been made to me, in proportion with my current friction.

stop(val, t=None)#

Work out whether I’ve been flung.

Changelog#

Unreleased#

See on GitHub: branch master | compare 2.0.0/master

pip install https://github.com/kivymd/KivyMD/archive/master.zip

1.1.1#

See on GitHub: tag 1.1.1 | compare 1.0.2/1.1.1

pip install kivymd==1.1.1

1.0.2#

See on GitHub: tag 1.0.2 | compare 1.0.1/1.0.2

pip install kivymd==1.0.2
  • Bug fixes and other minor improvements.

  • Added a button to copy the code to the documentation.

  • Added the feature to view code examples of documentation in imperative and declarative styles.

  • Added console scripts for developer tools.

1.0.1#

See on GitHub: tag 1.0.1 | compare 1.0.0/1.0.1

pip install kivymd==1.0.1

1.0.0#

See on GitHub: tag 1.0.0 | compare 0.104.2/1.0.0

pip install kivymd==1.0.0

0.104.2#

See on GitHub: tag 0.104.2 | compare 0.104.1/0.104.2

pip install kivymd==0.104.2
  • Bug fixes and other minor improvements.

  • Add HotReloadViewer class

  • Added features to Snackbar class: use padding, set custom button color, elevation

  • Add MDToggleButton class

  • Change to Material Design Baseline dark theme spec

  • Fix ReferenceError: weakly-referenced object no longer exists when start demo application

  • Changed the default value for the theme_text_color parameter in the BaseButton class (to the value “Primary”)

  • Fix setting of the text_color_normal and text_color_active parameters - earlier their values ​​did not affect anything

  • Fixed the length of the right edge of the border in relation to the hint text when the MDTextField is in the rectangle mode

  • Add get_tab_list method to MDTabs class

  • Add hover behavior when using MDDropdownMenu class

  • Added the feature to use the FitImage component to download images from the network

  • The elevation value for RectangularElevationBehavior and CircularElevationBehavior classes after pressing was always set to 2 - fixed

  • Methods that implement the ripple effect have always been called twice - fixed

  • The SmartTile class now uses the FitImage class to display images instead of the Image class

  • Removed dependency on PIL library

  • Add hint_bg_color, hint_text_color, hint_radius attributes to MDSlider class

  • Delete progressloader.py

  • Delete context_menu.py

  • Added the feature to control the properties of menu items during creation in MDDropdownMenu class

  • Added the feature to change the number of buttons after creating the MDFloatingActionButtonSpeedDial object

  • Added the feature to set the font_name property for the MDTabsLabel class

  • Add MDCarousel class

  • Delete kivymd/uix/useranimationcard.py

  • Added usage types for MDNavigationDrawer class: modal/standard

  • Added stencil instructions to the FitImage class canvas

  • Added on_ref_press and switch_tab methods to MDTabs class

  • Added on_release method for menu item events instead of callback method to MDDropdownMenu class

  • Added palette attribute - the feature to change the color of the MDSpinner when changing rotation cycles

  • Added the feature to change the border color of the MDRectangleFlatIconButton class

  • Add MDRelativeLayout class

  • Added the feature to use radius for MDNavigationDrawer corners

  • Removed UserAnimationCard class

  • Added feature to set background color for MDDialog class

  • Added MDNavigationRail component

  • Added MDSwiper component

  • Added ripple effect to MDTabs class

  • Added the feature to set toast positions on an Android device

  • Added of tooltips to MDToolbar icons

  • Fixed MDBottomAppBar notch transparency

  • Updated MDDatePicker class to material design specification.

  • Updated MDTimePicker class to material design specification.

  • Elevation behavior redesign to comply with the material design specification.

  • Removed the vendor package.

  • Added the feature to use a class instance (Kivy or KivyMD widget), which will be added to the MDDropdownMenu class menu header.

0.104.1#

See on GitHub: tag 0.104.1 | compare 0.104.0/0.104.1

pip install kivymd==0.104.1
  • Bug fixes and other minor improvements.

  • Added MDGridLayout and MDBoxLayout classes

  • Add TouchBehavior class

  • Add radius parameter to BackgroundColorBehavior class

  • Add MDScreen class

  • Add MDFloatLayout class

  • Added a MDTextField with fill mode

  • Added a shadow, increased speed of opening, added the feature to control the position of the MDDropdownMenu class

  • The MDDropDownItem class is now a regular element, such as a button

  • Added the ability to use the texture of the icon on the right in any MDTextField classes

  • Added the feature to use ripple and focus behavior in MDCard class

  • MDDialogs class redesigned to meet material design requirements

  • Added MDDataTable class

0.104.0#

See on GitHub: tag 0.104.0 | compare 0.103.0/0.104.0

pip install kivymd==0.104.0
  • Fixed bug in kivymd.uix.expansionpanel.MDExpansionPanel if, with the panel open, without closing it, try to open another panel, then the chevron of the first panel remained open.

  • The kivymd.uix.textfield.MDTextFieldRound class is now directly inherited from the kivy.uix.textinput.TextInput class.

  • Removed kivymd.uix.textfield.MDTextFieldClear class.

  • kivymd.uix.navigationdrawer.NavigationLayout allowed to add kivymd.uix.toolbar.MDToolbar class.

  • Added feature to control range of dates to be active in kivymd.uix.picker.MDDatePicker class.

  • Updated kivymd.uix.navigationdrawer.MDNavigationDrawer realization.

  • Removed kivymd.uix.card.MDCardPost class.

  • Added kivymd.uix.card.MDCardSwipe class.

  • Added switch_tab method for switching tabs to kivymd.uix.bottomnavigation.MDBottomNavigation class.

  • Added feature to use panel type in the kivymd.uix.expansionpanel.MDExpansionPanel class: kivymd.uix.expansionpanel.MDExpansionPanelOneLine, kivymd.uix.expansionpanel.MDExpansionPanelTwoLine or kivymd.uix.expansionpanel.MDExpansionPanelThreeLine.

  • Fixed panel opening animation in the kivymd.uix.expansionpanel.MDExpansionPanel class.

  • Delete kivymd.uix.managerswiper.py

  • Add MDFloatingActionButtonSpeedDial class

  • Added the feature to create text on tabs using markup, thereby triggering the on_ref_press event in the MDTabsLabel class

  • Added color_indicator attribute to set custom indicator color in the MDTabs class

  • Added the feature to change the background color of menu items in the BaseListItem class

  • Add MDTapTargetView class

0.103.0#

See on GitHub: tag 0.103.0 | compare 0.102.1/0.103.0

pip install kivymd==0.103.0
  • Fix MDSwitch size according to material design guides

  • Fix MDSwitch’s thumb position when size changes

  • Fix position of the icon relative to the right edge of the MDChip class on mobile devices

  • Updated MDBottomAppBar class.

  • Updated navigationdrawer.py

  • Added on_tab_switch method that is called when switching tabs (MDTabs class)

  • Added FpsMonitor class

  • Added fitimage.py - feature to automatically crop a Kivy image to fit your layout

  • Added animation when changing the action button position mode in MDBottomAppBar class

  • Delete fanscreenmanager.py

  • Bug fixes and other minor improvements.

0.102.1#

See on GitHub: tag 0.102.1 | compare 0.102.0/0.102.1

pip install kivymd==0.102.1

0.102.0#

See on GitHub: tag 0.102.0 | compare 0.101.8/0.102.0

pip install kivymd==0.102.0

0.101.8#

See on GitHub: tag 0.101.8 | compare 0.101.7/0.101.8

pip install https://github.com/kivymd/KivyMD/archive/0.101.8.zip
  • Added uix and behaviors folder to package_data.

0.101.7#

See on GitHub: tag 0.101.7 | compare 0.101.6/0.101.7

pip install https://github.com/kivymd/KivyMD/archive/0.101.7.zip

0.101.6#

See on GitHub: tag 0.101.6 | compare 0.101.5/0.101.6

pip install https://github.com/kivymd/KivyMD/archive/0.101.6.zip
  • Fixed NameError: name ‘MDThemePicker’ is not defined.

0.101.5#

See on GitHub: tag 0.101.5 | compare 0.101.4/0.101.5

pip install https://github.com/kivymd/KivyMD/archive/0.101.5.zip

0.101.4#

See on GitHub: tag 0.101.4 | compare 0.101.3/0.101.4

pip install https://github.com/kivymd/KivyMD/archive/0.101.4.zip
  • Bug fixes and other minor improvements.

0.101.3#

See on GitHub: tag 0.101.3 | compare 0.101.2/0.101.3

pip install https://github.com/kivymd/KivyMD/archive/0.101.3.zip
  • Bug fixes and other minor improvements.

0.101.2#

See on GitHub: tag 0.101.2 | compare 0.101.1/0.101.2

pip install https://github.com/kivymd/KivyMD/archive/0.101.2.zip
  • Bug fixes and other minor improvements.

0.101.1#

See on GitHub: tag 0.101.1 | compare 0.101.0/0.101.1

pip install https://github.com/kivymd/KivyMD/archive/0.101.1.zip
  • Bug fixes and other minor improvements.

0.101.0#

See on GitHub: tag 0.101.0 | compare 0.100.2/0.101.0

pip install https://github.com/kivymd/KivyMD/archive/0.101.0.zip

0.100.2#

See on GitHub: tag 0.100.2 | compare 0.100.1/0.100.2

pip install https://github.com/kivymd/KivyMD/archive/0.100.2.zip

0.100.1#

See on GitHub: tag 0.100.1 | compare 0.100.0/0.100.1

pip install https://github.com/kivymd/KivyMD/archive/0.100.1.zip
  • MDUserAnimationCard uses Image instead of AsyncImage.

0.100.0#

See on GitHub: tag 0.100.0 | compare 0.99.99/0.100.0

pip install https://github.com/kivymd/KivyMD/archive/0.100.0.zip
  • Added feature to change color for MDStackFloatingButtons.

0.99.99.01#

See on GitHub: tag 0.99.99.01 | compare 0.99.98/0.99.99.01

pip install https://github.com/kivymd/KivyMD/archive/0.99.99.01.zip
  • Fixed MDNavigationDrawer.use_logo.

0.99.99#

See on GitHub: tag 0.99.99 | compare 0.99.99.01/0.99.99

pip install https://github.com/kivymd/KivyMD/archive/0.99.99.zip
  • Added icon_color property for NavigationDrawerIconButton.

0.99.98#

See on GitHub: tag 0.99.98 | compare 0.99.97/0.99.98

pip install https://github.com/kivymd/KivyMD/archive/0.99.98.zip
  • Added MDFillRoundFlatIconButton class.

0.99.97#

See on GitHub: tag 0.99.97 | compare 0.99.96/0.99.97

pip install https://github.com/kivymd/KivyMD/archive/0.99.97.zip
  • Fixed Spinner animation.

0.99.96#

See on GitHub: tag 0.99.96 | compare 0.99.95/0.99.96

pip install https://github.com/kivymd/KivyMD/archive/0.99.96.zip

0.99.95#

See on GitHub: tag 0.99.95 | compare 0.99.94/0.99.95

pip install https://github.com/kivymd/KivyMD/archive/0.99.95.zip

0.99.94#

See on GitHub: tag 0.99.94 | compare 0.99.93/0.99.94

pip install https://github.com/kivymd/KivyMD/archive/0.99.94.zip
  • Added _no_ripple_effect property to BaseListItem class.

  • Added check to use ripple effect in RectangularRippleBehavior class.

  • [Disabled](https://www.youtube.com/watch?v=P_9oSx0Pz_U) using ripple effect in MDAccordionListItem class.

0.99.93#

See on GitHub: tag 0.99.93 | compare 0.99.92/0.99.93

pip install https://github.com/kivymd/KivyMD/archive/0.99.93.zip

0.99.92#

See on GitHub: tag 0.99.92 | compare 0.99.91/0.99.92

pip install https://github.com/kivymd/KivyMD/archive/0.99.92.zip
  • Removed automatic change of text field length in MDTextFieldRound class.

About#

License#

Refer to LICENSE.

MIT License

Copyright (c) 2024 Andrés Rodríguez and other contributors - KivyMD library up to version 0.1.2
Copyright (c) 2024 KivyMD Team and other contributors - KivyMD library version 0.1.3 and higher

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

KivyMD#

#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/previous.png

Is a collection of Material Design compliant widgets for use with, Kivy cross-platform graphical framework a framework for cross-platform, touch-enabled graphical applications. The project’s goal is to approximate Google’s Material Design spec as close as possible without sacrificing ease of use.

This library is a fork of the KivyMD project. We found the strength and brought this project to a new level.

If you wish to become a project developer (permission to create branches on the project without forking for easier collaboration), have at least one PR approved and ask for it. If you contribute regularly to the project the role may be offered to you without asking too.

API - kivymd#

kivymd.path#

Path to KivyMD package directory.

kivymd.fonts_path#

Path to fonts directory.

kivymd.images_path#

Path to images directory.

kivymd.uix_path#

Path to uix directory.

Submodules#

Register KivyMD widgets to use without import.#

Register KivyMD widgets to use without import.

API - kivymd.factory_registers#
kivymd.factory_registers.register#
Material Resources#
#
API - kivymd.material_resources#
kivymd.material_resources.dp#
kivymd.material_resources.DEVICE_IOS#
kivymd.material_resources.DEVICE_TYPE = 'desktop'#
Effects#
#
API - kivymd.effects#
Submodules#
kivymd.effects.stiffscroll#
API - kivymd.effects.stiffscroll#
Submodules#
kivymd.toast#
API - kivymd.toast#
Submodules#
AndroidToast#
#

Native implementation of toast for Android devices.

# Will be automatically used native implementation of the toast
# if your application is running on an Android device.
# On desktop use `MDSnackbar < https://kivymd.readthedocs.io/en/latest/components/snackbar/>`_

from kivy.lang import Builder

from kivymd.toast import toast
from kivymd.app import MDApp

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

     MDButton:
         pos_hint:{"center_x": .5, "center_y": .5}
         on_press: app.show_toast()

         MDButtonText:
             text: "Make toast"
'''


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

    def show_toast(self):
        toast("Hello World", True, 80, 200, 0)


Example().run()
API - kivymd.toast.androidtoast#
kivymd.toast.androidtoast.toast(text, length_long=False, gravity=0, y=0, x=0)#

Displays a toast.

Parameters:
  • length_long – the amount of time (in seconds) that the toast is visible on the screen;

  • text – text to be displayed in the toast;

  • length_long – duration of the toast, if True the toast will last 2.3s but if it is False the toast will last 3.9s;

  • gravity – refers to the toast position, if it is 80 the toast will be shown below, if it is 40 the toast will be displayed above;

  • y – refers to the vertical position of the toast;

  • x – refers to the horizontal position of the toast;

Important: if only the text value is specified and the value of the gravity, y, x parameters is not specified, their values will be 0 which means that the toast will be shown in the center.

kivymd.tools#
API - kivymd.tools#
Submodules#
kivymd.tools.argument_parser#
API - kivymd.tools.argument_parser#
class kivymd.tools.argument_parser.ArgumentParserWithHelp(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)#

Object for parsing command line strings into Python objects.

Keyword Arguments:
  • prog – The name of the program (default:

    os.path.basename(sys.argv[0]))

  • usage – A usage message (default: auto-generated from arguments)

  • description – A description of what the program does

  • epilog – Text following the argument descriptions

  • parents – Parsers whose arguments should be copied into this one

  • formatter_class – HelpFormatter class for printing help messages

  • prefix_chars – Characters that prefix optional arguments

  • fromfile_prefix_chars – Characters that prefix files containing

    additional arguments

  • argument_default – The default value for all arguments

  • conflict_handler – String indicating how to handle conflicts

  • add_help – Add a -h/-help option

  • allow_abbrev – Allow long options to be abbreviated unambiguously

  • exit_on_error – Determines whether or not ArgumentParser exits with

    error info when an error occurs

parse_args(args=None, namespace=None)#
error(message)#

error(message: string)

Prints a usage message incorporating the message to stderr and exits.

If you override this in a subclass, it should not return – it should either exit or raise an exception.

format_help()#
kivymd.tools.hotreload#
API - kivymd.tools.hotreload#
Submodules#
HotReload#
#

New in version 1.0.0.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hot-reload.png

Hot reload tool - is a fork of the project https://github.com/tito/kaki

Note

Since the project is not developing, we decided to include it in the KivvMD library and hope that the further development of the hot reload tool in the KivyMD project will develop faster.

This library enhance Kivy frameworks with opiniated features such as:

  • Auto reloading kv or py (watchdog required, limited to some uses cases);

  • Idle detection support;

  • Foreground lock (Windows OS only);

Usage#

Note

See create project with hot reload for more information.

TODO#
  • Add automatic reloading of Python classes;

  • Add save application state on reloading;

FIXME#
  • On Windows, hot reloading of Python files may not work;

API - kivymd.tools.hotreload.app#
kivymd.tools.hotreload.app.original_argv#
kivymd.tools.hotreload.app.monotonic#
kivymd.tools.hotreload.app.PY3 = True#
class kivymd.tools.hotreload.app.ExceptionClass#

Base handler that catches exceptions in runTouchApp(). You can subclass and extend it as follows:

class E(ExceptionHandler):
    def handle_exception(self, inst):
        Logger.exception('Exception caught by ExceptionHandler')
        return ExceptionManager.PASS

ExceptionManager.add_handler(E())

Then, all exceptions will be set to PASS, and logged to the console!

handle_exception(inst)#

Called by ExceptionManagerBase to handle a exception.

Defaults to returning ExceptionManager.RAISE that re-raises the exception. Return ExceptionManager.PASS to indicate that the exception was handled and should be ignored.

This may be called multiple times with the same exception, if ExceptionManager.RAISE is returned as the exception bubbles through multiple kivy exception handling levels.

class kivymd.tools.hotreload.app.MDApp(**kwargs)#

HotReload Application class.

property appname#

Return the name of the application class.

DEBUG#

Control either we activate debugging in the app or not. Defaults depend if ‘DEBUG’ exists in os.environ.

DEBUG is a BooleanProperty.

FOREGROUND_LOCK#

If True it will require the foreground lock on windows.

FOREGROUND_LOCK is a BooleanProperty and defaults to False.

KV_FILES#

List of KV files under management for auto reloader.

KV_FILES is a ListProperty and defaults to [].

KV_DIRS#

List of managed KV directories for autoloader.

KV_DIRS is a ListProperty and defaults to [].

AUTORELOADER_PATHS#

List of path to watch for auto reloading.

AUTORELOADER_PATHS is a ListProperty and defaults to ([(“.”, {“recursive”: True})].

AUTORELOADER_IGNORE_PATTERNS#

List of extensions to ignore.

AUTORELOADER_IGNORE_PATTERNS is a ListProperty and defaults to [‘*.pyc’, ‘*__pycache__*’].

CLASSES#

Factory classes managed by hotreload.

CLASSES is a DictProperty and defaults to {}.

IDLE_DETECTION#

Idle detection (if True, event on_idle/on_wakeup will be fired). Rearming idle can also be done with rearm_idle().

IDLE_DETECTION is a BooleanProperty and defaults to False.

IDLE_TIMEOUT#

Default idle timeout.

IDLE_TIMEOUT is a NumericProperty and defaults to 60.

RAISE_ERROR#

Raise error. When the DEBUG is activated, it will raise any error instead of showing it on the screen. If you still want to show the error when not in DEBUG, put this to False.

RAISE_ERROR is a BooleanProperty and defaults to True.

build()#

Initializes the application; it will be called only once. If this method returns a widget (tree), it will be used as the root widget and added to the window.

Returns:

None or a root Widget instance if no self.root exists.

get_root()#

Return a root widget, that will contains your application. It should not be your application widget itself, as it may be destroyed and recreated from scratch when reloading.

By default, it returns a RelativeLayout, but it could be a Viewport.

get_root_path()#

Return the root file path.

abstract build_app(first=False)#

Must return your application widget.

If first is set, it means that will be your first time ever that the application is built. Act according to it.

unload_app_dependencies()#

Called when all the application dependencies must be unloaded. Usually happen before a reload

load_app_dependencies()#

Load all the application dependencies. This is called before rebuild.

rebuild(*args, **kwargs)#
set_error(exc, tb=None)#
bind_key(key, callback)#

Bind a key (keycode) to a callback (cannot be unbind).

enable_autoreload()#

Enable autoreload manually. It is activated automatically if “DEBUG” exists in environ. It requires the watchdog module.

prepare_foreground_lock()#

Try forcing app to front permanently to avoid windows pop ups and notifications etc.app.

Requires fake full screen and borderless.

Note

This function is called automatically if FOREGROUND_LOCK is set

set_widget(wid)#

Clear the root container, and set the new approot widget to wid.

apply_state(state)#

Whatever the current state is, reapply the current state.

install_idle(timeout=60)#

Install the idle detector. Default timeout is 60s. Once installed, it will check every second if the idle timer expired. The timer can be rearm using rearm_idle().

rearm_idle(*args)#

Rearm the idle timer.

patch_builder()#
on_idle(*args)#

Event fired when the application enter the idle mode.

on_wakeup(*args)#

Event fired when the application leaves idle mode.

kivymd.tools.packaging#
API - kivymd.tools.packaging#
Submodules#
PyInstaller hooks#
#

Add hookspath=[kivymd.hooks_path] to your .spec file.

Example of .spec file#
# -*- mode: python ; coding: utf-8 -*-

import sys
import os

from kivy_deps import sdl2, glew

from kivymd import hooks_path as kivymd_hooks_path

path = os.path.abspath(".")

a = Analysis(
    ["main.py"],
    pathex=[path],
    hookspath=[kivymd_hooks_path],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=None,
    noarchive=False,
)
pyz = PYZ(a.pure, a.zipped_data, cipher=None)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    *[Tree(p) for p in (sdl2.dep_bins + glew.dep_bins)],
    debug=False,
    strip=False,
    upx=True,
    name="app_name",
    console=True,
)
API - kivymd.tools.packaging.pyinstaller#
kivymd.tools.packaging.pyinstaller.hooks_path#

Path to hook directory to use with PyInstaller. See kivymd.tools.packaging.pyinstaller for more information.

kivymd.tools.packaging.pyinstaller.get_hook_dirs()#
kivymd.tools.packaging.pyinstaller.get_pyinstaller_tests()#
Submodules#
PyInstaller hook for KivyMD#
#

Adds fonts, images and KV files to package.

All modules from uix directory are added by Kivy hook.

API - kivymd.tools.packaging.pyinstaller.hook-kivymd#
kivymd.tools.packaging.pyinstaller.hook-kivymd.datas = [(), ()]#
kivymd.tools.patterns#
API - kivymd.tools.patterns#
Submodules#
The script creates a new View package#
#

The script creates a new View package in an existing project with an MVC template created using the create_project utility.

New in version 1.0.0.

Use a clean architecture for your applications.

To add a new view to an existing project that was created using the create_project utility, use the following command:

kivymd.add_view \
    name_pattern \
    path_to_project \
    name_view

Example command:

kivymd.add_view \
    MVC \
    /Users/macbookair/Projects \
    NewScreen

You can also add new views with responsive behavior to an existing project:

kivymd.add_view \
    MVC \
    /Users/macbookair/Projects \
    NewScreen \
    --use_responsive yes

For more information about adaptive design, see here.

API - kivymd.tools.patterns.add_view#
kivymd.tools.patterns.add_view.main()#

The function of adding a new view to the project.

Script creates a project with the MVC pattern#
#

New in version 1.0.0.

See also

MVC pattern

Use a clean architecture for your applications.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/preview-mvc.png

Use a clean architecture for your applications. KivyMD allows you to quickly create a project template with the MVC pattern. So far, this is the only pattern that this utility offers. You can also include database support in your project. At the moment, support for the Firebase database (the basic implementation of the real time database) and RestDB (the full implementation) is available.

Project creation#

Template command:

kivymd.create_project \
    name_pattern \
    path_to_project \
    name_project \
    python_version \
    kivy_version

Example command:

kivymd.create_project \
    MVC \
    /Users/macbookair/Projects \
    MyMVCProject \
    python3.10 \
    2.1.0

This command will by default create a project with an MVC pattern. Also, the project will create a virtual environment with Python 3.10, Kivy version 2.1.0 and KivyMD master version.

Note

Please note that the Python version you specified must be installed on your computer.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mvc-base.png
Creating a project using a database#

Note

Note that in the following command, you can use one of two database names: ‘firebase’ or ‘restdb’.

Template command:

kivymd.create_project \
    name_pattern \
    path_to_project \
    name_project \
    python_version \
    kivy_version \
    --name_database

Example command:

kivymd.create_project \
    MVC \
    /Users/macbookair/Projects \
    MyMVCProject \
    python3.10 \
    2.1.0 \
    --name_database restdb

This command will create a project with an MVC template by default. The project will also create a virtual environment with Python 3.10, Kivy version 2.1.0, KivyMD master version and a wrapper for working with the database restdb.io.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mvc-database.png
class DataBase:
    def __init__(self):
        database_url = "https://restdbio-5498.restdb.io"
        api_key = "7ce258d66f919d3a891d1166558765f0b4dbd"

Note

Please note that database.py the shell in the DataBase class uses the database_url and api_key parameters on the test database (works only in read mode), so you should use your data for the database.

Create project with hot reload#

Template command:

kivymd.create_project \
    name_pattern \
    path_to_project \
    name_project \
    python_version \
    kivy_version \
    --use_hotreload

Example command:

kivymd.create_project \
    MVC \
    /Users/macbookair/Projects \
    MyMVCProject \
    python3.10 \
    2.1.0 \
    --use_hotreload yes

After creating the project, open the file main.py, there is a lot of useful information. Also, the necessary information is in other modules of the project in the form of comments. So do not forget to look at the source files of the created project.

Create project with responsive view#

When creating a project, you can specify which views should use responsive behavior. To do this, specify the name of the view/views in the –use_responsive argument:

Template command:

kivymd.create_project \
    name_pattern \
    path_to_project \
    name_project \
    python_version \
    kivy_version \
    --name_screen FirstScreen SecondScreen ThirdScreen \
    --use_responsive FirstScreen SecondScreen

The FirstScreen and SecondScreen views will be created with an responsive architecture. For more detailed information about using the adaptive view, see the MDResponsiveLayout widget.

Others command line arguments#
Required Arguments#
  • pattern
    • the name of the pattern with which the project will be created

  • directory
    • directory in which the project will be created

  • name
    • project name

  • python_version
    • the version of Python (specify as python3.9 or python3.8) with

    • which the virtual environment will be created

  • kivy_version
    • version of Kivy (specify as 2.1.0 or master) that will be used in the project

Optional arguments#
  • name_screen
    • the name of the class which be used when creating the project pattern

When you need to create an application template with multiple screens, use multiple values separated by a space for the name_screen parameter, for example, as shown below:

Template command:

kivymd.create_project \
    name_pattern \
    path_to_project \
    name_project \
    python_version \
    kivy_version \
    --name_screen FirstScreen SecondScreen ThirdScreen
  • name_database
    • provides a basic template for working with the ‘firebase’ library

    • or a complete implementation for working with a database ‘restdb.io’

  • use_hotreload
    • creates a hot reload entry point to the application

  • use_localization
    • creates application localization files

  • use_responsive
    • the name/names of the views to be used by the responsive UI

Warning

On Windows, hot reloading of Python files may not work. But, for example, there is no such problem in macOS. If you fix this, please report it to the KivyMD community.

API - kivymd.tools.patterns.create_project#
kivymd.tools.patterns.create_project.main()#

Project creation function.

kivymd.tools.patterns.MVC#
API - kivymd.tools.patterns.MVC#
Submodules#
kivymd.tools.patterns.MVC.Model#
API - kivymd.tools.patterns.MVC.Model#
Submodules#
kivymd.tools.patterns.MVC.Model.database_firebase#
API - kivymd.tools.patterns.MVC.Model.database_firebase#
kivymd.tools.patterns.MVC.Model.database_firebase.get_connect(func, host='8.8.8.8', port=53, timeout=3)#

Checks for an active Internet connection.

class kivymd.tools.patterns.MVC.Model.database_firebase.DataBase#

Your methods for working with the database should be implemented in this class.

name = 'Firebase'#
get_data_from_collection(name_collection: str) dict | bool#

Returns data of the selected collection from the database.

Restdb.io API Wrapper#
#

This package is an API Wrapper for the website restdb.io, which allows for online databases.

API - kivymd.tools.patterns.MVC.Model.database_restdb#
kivymd.tools.patterns.MVC.Model.database_restdb.get_connect(func, host='8.8.8.8', port=53, timeout=3)#

Checks for an active Internet connection.

class kivymd.tools.patterns.MVC.Model.database_restdb.DataBase#
name = 'RestDB'#
upload_file(path_to_file: str) dict | bool#

Uploads a file to the database. You can upload a file to the database only from a paid account.

get_data_from_collection(collection_address: str) bool | list#

Returns data of the selected collection from the database.

delete_doc_from_collection(collection_address: str) bool#

Delete data of the selected collection from the database.

Parameters:

collection_address – “database_url/id_collection”.

add_doc_to_collection(data: dict, collection_address: str) bool#

Add collection to the database.

edit_data(collection: dict, collection_address: str, collection_id: str) bool#

Modifies data in a collection of data in a database.

kivymd.tools.patterns.MVC.libs#
API - kivymd.tools.patterns.MVC.libs#
Submodules#
kivymd.tools.patterns.MVC.libs.translation#
API - kivymd.tools.patterns.MVC.libs.translation#
class kivymd.tools.patterns.MVC.libs.translation.Translation(defaultlang, domian, resource_dir)#

Original source - https://github.com/tito/kivy-gettext-example.

observers = []#
fbind(name, func, args, **kwargs)#
funbind(name, func, args, **kwargs)#
switch_lang(lang)#
kivymd.tools.release#
API - kivymd.tools.release#
Submodules#
kivymd.tools.release.git_commands#
API - kivymd.tools.release.git_commands#
kivymd.tools.release.git_commands.command(cmd: list, capture_output: bool = False) str#

Run system command.

kivymd.tools.release.git_commands.get_previous_version() str#

Returns latest tag in git.

kivymd.tools.release.git_commands.git_clean(ask: bool = True)#

Clean git repository from untracked and changed files.

kivymd.tools.release.git_commands.git_commit(message: str, allow_error: bool = False, add_files: list = None)#

Make commit.

kivymd.tools.release.git_commands.git_tag(name: str)#

Create tag.

kivymd.tools.release.git_commands.git_push(branches_to_push: list, ask: bool = True, push: bool = False)#

Push all changes.

Script to make release#
#

Run this script before release (before deploying).

What this script does:

  • Undo all local changes in repository

  • Update version in __init__.py, README.md

  • Format files

  • Rename file “unreleased.rst” to version, add to index.rst

  • Commit “Version …”

  • Create tag

  • Add unreleased.rst to Changelog, add to index.rst

  • Commit

  • Git push

API - kivymd.tools.release.make_release#
kivymd.tools.release.make_release.run_pre_commit()#

Run pre-commit.

kivymd.tools.release.make_release.replace_in_file(pattern, repl, file)#

Replace one pattern match to repl in file file.

kivymd.tools.release.make_release.update_version_py(version, is_release, test: bool = False)#

Change version in kivymd/_version.py.

kivymd.tools.release.make_release.update_readme(previous_version, version, test: bool = False)#

Change version in README.md.

kivymd.tools.release.make_release.move_changelog(index_file, unreleased_file, previous_version, version_file, version, test: bool = False)#

Edit unreleased.rst and rename to <version>.rst.

kivymd.tools.release.make_release.create_unreleased_changelog(index_file, unreleased_file, version, ask: bool = True, test: bool = False)#

Create unreleased.rst by template.

kivymd.tools.release.make_release.main()#
kivymd.tools.release.make_release.create_argument_parser()#
Tool for updating Iconic font#
#

Downloads archive from https://github.com/Templarian/MaterialDesign-Webfont and updates font file with icon_definitions.

API - kivymd.tools.release.update_icons#
kivymd.tools.release.update_icons.kivymd_path#
kivymd.tools.release.update_icons.font_path#
kivymd.tools.release.update_icons.icon_definitions_path#
kivymd.tools.release.update_icons.font_version = 'master'#
kivymd.tools.release.update_icons.url#
kivymd.tools.release.update_icons.temp_path#
kivymd.tools.release.update_icons.temp_repo_path#
kivymd.tools.release.update_icons.temp_font_path#
kivymd.tools.release.update_icons.temp_preview_path#
kivymd.tools.release.update_icons.re_icons_json#
kivymd.tools.release.update_icons.re_additional_icons#
kivymd.tools.release.update_icons.re_version#
kivymd.tools.release.update_icons.re_quote_keys#
kivymd.tools.release.update_icons.re_icon_definitions#
kivymd.tools.release.update_icons.re_version_in_file#
kivymd.tools.release.update_icons.download_file(url, path)#
kivymd.tools.release.update_icons.unzip_archive(archive_path, dir_path)#
kivymd.tools.release.update_icons.get_icons_list()#
kivymd.tools.release.update_icons.make_icon_definitions(icons)#
kivymd.tools.release.update_icons.export_icon_definitions(icon_definitions, version)#
kivymd.tools.release.update_icons.update_icons(make_commit: bool = False)#
kivymd.tools.release.update_icons.main()#
kivymd.uix#
API - kivymd.uix#
class kivymd.uix.MDAdaptiveWidget#
adaptive_height#

If True, the following properties will be applied to the widget:

size_hint_y: None
height: self.minimum_height

adaptive_height is an BooleanProperty and defaults to False.

adaptive_width#

If True, the following properties will be applied to the widget:

size_hint_x: None
width: self.minimum_width

adaptive_width is an BooleanProperty and defaults to False.

adaptive_size#

If True, the following properties will be applied to the widget:

size_hint: None, None
size: self.minimum_size

adaptive_size is an BooleanProperty and defaults to False.

on_adaptive_height(md_widget, value: bool) None#
on_adaptive_width(md_widget, value: bool) None#
on_adaptive_size(md_widget, value: bool) None#
Submodules#
kivymd.uix.appbar#
API - kivymd.uix.appbar#
Submodules#
kivymd.uix.badge#
API - kivymd.uix.badge#
Submodules#
Behaviors#
#

Modules and classes implementing various behaviors for buttons etc.

API - kivymd.uix.behaviors#
Submodules#
kivymd.uix.bottomsheet#
API - kivymd.uix.bottomsheet#
Submodules#
kivymd.uix.button#
API - kivymd.uix.button#
Submodules#
kivymd.uix.card#
API - kivymd.uix.card#
Submodules#
kivymd.uix.chip#
API - kivymd.uix.chip#
Submodules#
Controllers#
#

New in version 1.0.0.

Modules and classes that implement useful methods for getting information about the state of the current application window.

API - kivymd.uix.controllers#
Submodules#
kivymd.uix.dialog#
API - kivymd.uix.dialog#
Submodules#
kivymd.uix.divider#
API - kivymd.uix.divider#
Submodules#
kivymd.uix.dropdownitem#
API - kivymd.uix.dropdownitem#
Submodules#
kivymd.uix.expansionpanel#
API - kivymd.uix.expansionpanel#
Submodules#
kivymd.uix.filemanager#
API - kivymd.uix.filemanager#
Submodules#
kivymd.uix.fitimage#
API - kivymd.uix.fitimage#
Submodules#
kivymd.uix.imagelist#
API - kivymd.uix.imagelist#
Submodules#
kivymd.uix.label#
API - kivymd.uix.label#
Submodules#
kivymd.uix.list#
API - kivymd.uix.list#
Submodules#
kivymd.uix.menu#
API - kivymd.uix.menu#
Submodules#
kivymd.uix.navigationbar#
API - kivymd.uix.navigationbar#
Submodules#
kivymd.uix.navigationdrawer#
API - kivymd.uix.navigationdrawer#
Submodules#
kivymd.uix.navigationrail#
API - kivymd.uix.navigationrail#
Submodules#
kivymd.uix.pickers#
API - kivymd.uix.pickers#
Submodules#
kivymd.uix.pickers.datepicker#
API - kivymd.uix.pickers.datepicker#
Submodules#
kivymd.uix.pickers.timepicker#
API - kivymd.uix.pickers.timepicker#
Submodules#
kivymd.uix.progressindicator#
API - kivymd.uix.progressindicator#
Submodules#
kivymd.uix.refreshlayout#
API - kivymd.uix.refreshlayout#
Submodules#
kivymd.uix.segmentedbutton#
API - kivymd.uix.segmentedbutton#
Submodules#
kivymd.uix.selectioncontrol#
API - kivymd.uix.selectioncontrol#
Submodules#
kivymd.uix.slider#
API - kivymd.uix.slider#
Submodules#
kivymd.uix.sliverappbar#
API - kivymd.uix.sliverappbar#
Submodules#
kivymd.uix.snackbar#
API - kivymd.uix.snackbar#
Submodules#
kivymd.uix.swiper#
API - kivymd.uix.swiper#
Submodules#
kivymd.uix.tab#
API - kivymd.uix.tab#
Submodules#
kivymd.uix.textfield#
API - kivymd.uix.textfield#
Submodules#
kivymd.uix.tooltip#
API - kivymd.uix.tooltip#
Submodules#
kivymd.uix.transition#
API - kivymd.uix.transition#
Submodules#
kivymd.utils#
API - kivymd.utils#
Submodules#
Monitor module#
#

The Monitor module is a toolbar that shows the activity of your current application :

  • FPS

API - kivymd.utils.fpsmonitor#
class kivymd.utils.fpsmonitor.FpsMonitor(**kwargs)#

Fps monitor class.

For more information, see in the Label class documentation.

updated_interval#

FPS refresh rate.

updated_interval is an NumericProperty and defaults to 0.5.

anchor#

Monitor position. Available option are: ‘top’, ‘bottom’.

anchor is an OptionProperty and defaults to ‘top’.

start() None#

Monitor starting.

update_fps(*args) None#
kivymd.utils.set_bars_colors#
API - kivymd.utils.set_bars_colors#
kivymd.utils.set_bars_colors.set_bars_colors(status_bar_color: None | list, navigation_bar_color: None | list, icons_color: str = 'Light')#

Sets the color of the status of the StatusBar and NavigationBar.

Warning

Works only on Android devices.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/status-bar-color-light.png
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.utils.set_bars_colors import set_bars_colors

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

    MDTopAppBar:
        title: "MDTopAppBar"

    MDBottomNavigation:
        panel_color: app.theme_cls.primary_color
        text_color_active: .2, .2, .2, 1
        text_color_normal: .9, .9, .9, 1
        use_text: False

        MDBottomNavigationItem:
            icon: 'gmail'

        MDBottomNavigationItem:
            icon: 'twitter'

        MDBottomNavigationItem:
            icon: 'youtube'
'''


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

    def set_bars_colors(self):
        set_bars_colors(
            self.theme_cls.primary_color,  # status bar color
            self.theme_cls.primary_color,  # navigation bar color
            "Light",                       # icons color of status bar
        )


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-bar-color.png

Dark icon mode

def set_bars_colors(self):
    set_bars_colors(
        self.theme_cls.primary_color,  # status bar color
        self.theme_cls.primary_color,  # navigation bar color
        "Dark",                        # icons color of status bar
    )
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/status-bar-color-dark.png

New in version 1.0.0.

Indices and tables#