Welcome to KivyMD’s documentation!#
KivyMD#

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:

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:

Kivy:

Themes#
Theming#
#
See also
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()
from kivymd.app import MDApp from kivymd.uix.button import MDButton, MDButtonIcon, MDButtonText from kivymd.uix.screen import MDScreen class Example(MDApp): def build(self): self.theme_cls.theme_style = "Dark" self.theme_cls.primary_palette = "Olive" # "Purple", "Red" return ( MDScreen( MDButton( MDButtonIcon( icon="plus", ), MDButtonText( text="Button", ), style="elevated", pos_hint={"center_x": 0.5, "center_y": 0.5}, ), md_bg_color=self.theme_cls.backgroundColor, ) ) Example().run()
primary_palette
is anOptionProperty
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 anNumericProperty
and defaults to 10 if platform is not Android else 1.
- dynamic_color#
Enables or disables dynamic color.
New in version 2.0.0.
See also
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 anBooleanProperty
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 anOptionProperty
and defaults to ‘TONAL_SPOT’.
- dynamic_scheme_contrast#
The contrast of the generated color scheme.
dynamic_scheme_contrast
is anNumericProperty
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 anStringProperty
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()
from kivy.clock import Clock from kivymd.app import MDApp from kivymd.uix.button import MDButton, MDButtonText from kivymd.uix.card import MDCard from kivymd.uix.label import MDLabel from kivymd.uix.screen import MDScreen 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 ( MDScreen( MDCard( MDLabel( id="label", text="Theme style - {}".format( self.theme_cls.theme_style), halign="center", valign="center", bold=True, font_style="Display", role="small", ), MDButton( MDButtonText( text="Set theme", ), on_release=self.switch_theme_style, pos_hint={"center_x": 0.5}, ), id="card", orientation="vertical", padding=(0, 0, 0, "36dp"), size_hint=(0.5, 0.5), pos_hint={"center_x": 0.5, "center_y": 0.5}, style="elevated", ) ) ) 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) def switch_theme_style(self, *args): 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" ) self.root.get_ids().label.text = ( "Theme style - {}".format(self.theme_cls.theme_style) ) Example().run()
theme_style_switch_animation
is anBooleanProperty
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
theme_style_switch_animation_duration
is anNumericProperty
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()
theme_style
is anOptionProperty
and defaults to ‘Light’.
- disabled_hint_text_color#
Color of the disabled text used in the
MDTextField
.disabled_hint_text_color
is anAliasProperty
that returns the value inrgba
format fordisabled_hint_text_color
, property is readonly.
- device_orientation#
Device orientation.
device_orientation
is anStringProperty
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()
from kivy.core.text import LabelBase from kivy.metrics import sp from kivymd.uix.label import MDLabel from kivymd.uix.screen import MDScreen from kivymd.app import MDApp class Example(MDApp): def build(self): self.theme_cls.theme_style = "Dark" LabelBase.register( name="nasalization", fn_regular="/Users/urijivanov/Projects/Dev/MyGithub/Articles/StarTest/data/font/nasalization-rg.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 ( MDScreen( MDLabel( text="JetBrainsMono", halign="center", font_style="nasalization", ) ) ) Example().run()
font_styles
is anDictProperty
.
- on_colors#
A Helper function called when colors are changed.
- Attr:
on_colors defaults to None.
- on_dynamic_scheme_name(*args)#
- on_dynamic_scheme_contrast(*args)#
- on_path_to_wallpaper(*args)#
- class kivymd.theming.ThemableBehavior(**kwargs)#
- theme_cls#
Instance of
ThemeManager
class.theme_cls
is anObjectProperty
.
- device_ios#
True
if device isiOS
.device_ios
is anBooleanProperty
.
- theme_line_color#
Line color scheme name.
New in version 2.0.0.
Available options are: ‘Primary’, ‘Custom’.
theme_line_color
is anOptionProperty
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 anOptionProperty
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 anOptionProperty
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 anOptionProperty
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 anOptionProperty
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 anOptionProperty
and defaults to ‘Primary’.
- theme_width#
Widget width scheme name.
New in version 2.0.0.
Available options are: ‘Primary’, ‘Custom’.
theme_width
is anOptionProperty
and defaults to ‘Primary’.
- theme_height#
Widget width scheme name.
New in version 2.0.0.
Available options are: ‘Primary’, ‘Custom’.
theme_height
is anOptionProperty
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 anOptionProperty
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 anOptionProperty
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 anOptionProperty
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 anOptionProperty
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 anOptionProperty
and defaults to ‘Primary’.
- theme_text_color#
Label color scheme name.
Available options are: ‘Primary’, ‘Secondary’, ‘Hint’, ‘Error’, ‘Custom’.
theme_text_color
is anOptionProperty
and defaults to ‘Primary’.
- theme_icon_color#
Label color scheme name.
Available options are: ‘Primary’, ‘Secondary’, ‘Hint’, ‘Error’, ‘Custom’.
theme_icon_color
is anOptionProperty
and defaults to ‘Primary’.
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()

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 anStringProperty
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 theMDApp
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 anObjectProperty
.
- 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.
Icon Definitions#
#

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

API - kivymd.icon_definitions
#
- kivymd.icon_definitions.md_icons#
Font definitions#
#
API - kivymd.font_definitions
#
- kivymd.font_definitions.fonts#
- kivymd.font_definitions.theme_font_styles#
Components#
Dynamic color#
#
See also
Dynamic color can create accessible UI color schemes based on content or user settings

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.

Baseline scheme
Colors extracted from a wallpaper
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()

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

API - kivymd.dynamic_color
#
- class kivymd.dynamic_color.DynamicColor#
Dynamic color class.
New in version 2.0.0.
- primaryColor#
Primary color.
primaryColor
is anColorProperty
and defaults to None.
- primaryContainerColor#
Primary container color.
primaryContainerColor
is anColorProperty
and defaults to None.
- onPrimaryColor#
On primary color.
onPrimaryColor
is anColorProperty
and defaults to None.
- onPrimaryContainerColor#
On primary container color.
onPrimaryContainerColor
is anColorProperty
and defaults to None.
- secondaryColor#
Secondary color.
secondaryColor
is anColorProperty
and defaults to None.
- secondaryContainerColor#
Secondary container color.
secondaryContainerColor
is anColorProperty
and defaults to None.
- onSecondaryColor#
On secondary color.
onSecondaryColor
is anColorProperty
and defaults to None.
- onSecondaryContainerColor#
On secondary container color.
onSecondaryContainerColor
is anColorProperty
and defaults to None.
- tertiaryColor#
Tertiary color.
tertiaryColor
is anColorProperty
and defaults to None.
- tertiaryContainerColor#
Tertiary container color.
tertiaryContainerColor
is anColorProperty
and defaults to None.
- onTertiaryColor#
On tertiary color.
onTertiaryColor
is anColorProperty
and defaults to None.
- onTertiaryContainerColor#
On tertiary container color.
onTertiaryContainerColor
is anColorProperty
and defaults to None.
- surfaceColor#
Surface color.
surfaceColor
is anColorProperty
and defaults to None.
- surfaceDimColor#
Surface dim color.
surfaceDimColor
is anColorProperty
and defaults to None.
- surfaceBrightColor#
Surface bright color.
surfaceBrightColor
is anColorProperty
and defaults to None.
- surfaceContainerLowestColor#
Surface container lowest color.
surfaceContainerLowestColor
is anColorProperty
and defaults to None.
- surfaceContainerLowColor#
Surface container low color.
surfaceContainerLowColor
is anColorProperty
and defaults to None.
- surfaceContainerColor#
Surface container color.
surfaceContainerColor
is anColorProperty
and defaults to None.
- surfaceContainerHighColor#
Surface container high color.
surfaceContainerHighColor
is anColorProperty
and defaults to None.
- surfaceContainerHighestColor#
Surface container highest color.
surfaceContainerHighestColor
is anColorProperty
and defaults to None.
- surfaceVariantColor#
Surface variant color.
surfaceVariantColor
is anColorProperty
and defaults to None.
- surfaceTintColor#
Surface tint color.
surfaceTintColor
is anColorProperty
and defaults to None.
- onSurfaceColor#
On surface color.
onSurfaceColor
is anColorProperty
and defaults to None.
- onSurfaceLightColor#
On surface light color.
onSurfaceLightColor
is anColorProperty
and defaults to None.
- onSurfaceVariantColor#
On surface variant color.
onSurfaceVariantColor
is anColorProperty
and defaults to None.
- inverseSurfaceColor#
Inverse surface color.
inverseSurfaceColor
is anColorProperty
and defaults to None.
- inverseOnSurfaceColor#
Inverse on surface color.
inverseOnSurfaceColor
is anColorProperty
and defaults to None.
- inversePrimaryColor#
Inverse primary color.
inversePrimaryColor
is anColorProperty
and defaults to None.
- backgroundColor#
Background color.
backgroundColor
is anColorProperty
and defaults to None.
- onBackgroundColor#
On background color.
onBackgroundColor
is anColorProperty
and defaults to None.
- errorColor#
Error color.
errorColor
is anColorProperty
and defaults to None.
- errorContainerColor#
Error container color.
errorContainerColor
is anColorProperty
and defaults to None.
- onErrorColor#
On error color.
onErrorColor
is anColorProperty
and defaults to None.
- onErrorContainerColor#
On error container color.
onErrorContainerColor
is anColorProperty
and defaults to None.
- outlineColor#
Outline color.
outlineColor
is anColorProperty
and defaults to None.
- outlineVariantColor#
Outline variant color.
outlineVariantColor
is anColorProperty
and defaults to None.
- shadowColor#
Shadow color.
shadowColor
is anColorProperty
and defaults to None.
- scrimColor#
Scrim color.
scrimColor
is anColorProperty
and defaults to None.
- disabledTextColor#
Disabled text color.
disabledTextColor
is anColorProperty
and defaults to None.
- transparentColor#
Transparent color.
transparentColor
is anColorProperty
and defaults to [0, 0, 0, 0].
- rippleColor#
Ripple color.
rippleColor
is anColorProperty
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
andThemableBehavior
andBackgroundColorBehavior
andFloatLayout
andMDAdaptiveWidget
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
andThemableBehavior
andBackgroundColorBehavior
andGridLayout
andMDAdaptiveWidget
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
andThemableBehavior
andBackgroundColorBehavior
andRecycleView
andMDAdaptiveWidget
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 atdampedscrolleffect
.- 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
andBackgroundColorBehavior
andScrollView
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.
- touch:
- 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
andThemableBehavior
andBackgroundColorBehavior
andStackLayout
andMDAdaptiveWidget
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
andThemableBehavior
andBackgroundColorBehavior
andRelativeLayout
andMDAdaptiveWidget
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()

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 anObjectProperty
and defaults to None.
- tablet_view#
Tablet view. Must be a Kivy or KivyMD widget.
tablet_view
is anObjectProperty
and defaults to None.
- desktop_view#
Desktop view. Must be a Kivy or KivyMD widget.
desktop_view
is anObjectProperty
and defaults to None.
- on_change_screen_type(*args)#
Called when the screen type changes.
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.

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

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

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

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

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

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 anStringProperty
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 anStringProperty
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
andThemableBehavior
andBackgroundColorBehavior
andAnchorLayout
andMDAdaptiveWidget
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
andThemableBehavior
andBackgroundColorBehavior
andRecycleGridLayout
andMDAdaptiveWidget
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
andThemableBehavior
andBackgroundColorBehavior
andScreenManager
andMDAdaptiveWidget
classes documentation.- current_hero#
The name of the current tag for the
MDHeroFrom
andMDHeroTo
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 anStringProperty
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 anListProperty
and defaults to [].
- get_hero_from_widget() list #
Get a list of
MDHeroFrom
objects according to the tag names specified in thecurrent_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
andThemableBehavior
andBackgroundColorBehavior
andMDAdaptiveWidget
andWidget
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
andThemableBehavior
andBackgroundColorBehavior
andBoxLayout
andMDAdaptiveWidget
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
andThemableBehavior
andBackgroundColorBehavior
andScreen
andMDAdaptiveWidget
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 anObjectProperty
and defaults to None.
- heroes_to#
Must be a list of
MDHeroTo
class.New in version 1.0.0.
heroes_to
is anLiatProperty
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()

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 anNumericProperty
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 anNumericProperty
and defaults to None.
- start_from#
The positon of first child in degree.
start_from
is anNumericProperty
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 anNumericProperty
and defaults to 360.
- circular_padding#
Padding between outer widgets and the edge of the biggest circle.
circular_padding
is anNumericProperty
and defaults to 25dp.
- row_spacing#
Space between each row of widget.
row_spacing
is anNumericProperty
and defaults to 50dp.
- clockwise#
Direction of widgets in circular direction.
clockwise
is anBooleanProperty
and defaults to True.
- remove_widget(widget, **kwargs)#
Remove a widget from the children of this widget.
- Parameters:
- widget:
Widget
Widget to remove from our children list.
- widget:
>>> 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.
ExpansionPanel#
#
Expansion panels contain creation flows and allow lightweight editing of an element.

Usage#
MDExpansionPanel:
MDExpansionPanelHeader:
# Content of header.
[...]
MDExpansionPanelContent:
# Content of panel.
[...]
Anatomy#

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

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

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
andThemableBehavior
andBackgroundColorBehavior
andBoxLayout
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
andBoxLayout
classes documentation.
- class kivymd.uix.expansionpanel.expansionpanel.MDExpansionPanel(**kwargs)#
Expansion panel class.
For more information, see in the
DeclarativeBehavior
andBoxLayout
classes documentation.- opening_transition#
The name of the animation transition type to use when animating to the
state
‘open’.opening_transition
is aStringProperty
and defaults to ‘out_cubic’.
- opening_time#
The time taken for the panel to slide to the
state
‘open’.opening_time
is aNumericProperty
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 aStringProperty
and defaults to ‘out_sine’.
- closing_time#
The time taken for the panel to slide to the
state
‘close’.closing_time
is aNumericProperty
and defaults to 0.2.
- is_open#
The panel is open or closed.
New in version 2.0.0.
is_open
is aBooleanProperty
and defaults to False.
- 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.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
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)

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

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

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
andRelativeLayout
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 anStringProperty
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", )
icon_selection_button
is anStringProperty
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", )
background_color_selection_button
is anColorProperty
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", )
background_color_toolbar
is anColorProperty
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", )
icon
is anStringProperty
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", )
icon_color
is anColorProperty
and defaults to None.
- exit_manager#
Function called when the user reaches directory tree root.
exit_manager
is anObjectProperty
and defaults to lambda x: None.
- select_path#
Function, called when selecting a file/directory.
select_path
is anObjectProperty
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 anListProperty
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 anOptionProperty
and defaults to all.
- current_path#
Current directory.
current_path
is anStringProperty
and defaults to os.path.expanduser(“~”).
- use_access#
Show access to files and directories.
use_access
is anBooleanProperty
and defaults to True.
- preview#
Shows only image previews.
preview
is anBooleanProperty
and defaults to False.
Shows hidden files.
show_hidden_files
is anBooleanProperty
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 anOptionProperty
and defaults to name.
- sort_by_desc#
Sort by descending.
sort_by_desc
is anBooleanProperty
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 anOptionProperty
and defaults to any.
- selection#
Contains the list of files that are currently selected.
selection
is a read-onlyListProperty
and defaults to [].
- selection_button#
The instance of the directory/path selection button.
New in version 1.1.0.
selection_button
is a read-onlyObjectProperty
and defaults to 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_content() Tuple[List[str], List[str]] | Tuple[None, None] #
Returns a list of the type [[Folder List], [file list]].
- select_dir_or_file(path: str, widget: MDFileManagerItemPreview | MDFileManagerItem) None #
Called by tap on the name of the directory or file.
- on_background_color_toolbar(instance_file_manager, color: str | list) None #
Called when the
background_color_toolbar
property is changed.
List#
#
See also
Lists are continuous, vertical indexes of text or images.

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#

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()
from kivymd.uix.list import MDListItem, MDListItemHeadlineText
from kivymd.uix.screen import MDScreen
from kivymd.app import MDApp
class Example(MDApp):
def build(self):
return (
MDScreen(
MDListItem(
MDListItemHeadlineText(
text="Headline",
),
pos_hint={"center_x": .5, "center_y": .5},
size_hint_x=0.8,
),
md_bg_color=self.theme_cls.backgroundColor,
)
)
Example().run()

Two line list item#
MDListItem:
MDListItemHeadlineText:
text: "Headline"
MDListItemSupportingText:
text: "Supporting text"
MDListItem(
MDListItemHeadlineText(
text="Headline",
),
MDListItemSupportingText(
text="Supporting text",
),
)

Three line list item#
MDListItem:
MDListItemHeadlineText:
text: "Headline"
MDListItemSupportingText:
text: "Supporting text"
MDListItemTertiaryText:
text: "Tertiary text"
MDListItem(
MDListItemHeadlineText(
text="Headline",
),
MDListItemSupportingText(
text="Supporting text",
),
MDListItemTertiaryText(
text="Tertiary text",
),
)

List item with leading icon#
MDListItem:
MDListItemLeadingIcon:
icon: "account"
MDListItemHeadlineText:
text: "Headline"
MDListItemSupportingText:
text: "Supporting text"
MDListItemTertiaryText:
text: "Tertiary text"
MDListItem(
MDListItemLeadingIcon(
icon="account",
),
MDListItemHeadlineText(
text="Headline",
),
MDListItemSupportingText(
text="Supporting text",
),
MDListItemTertiaryText(
text="Tertiary text",
),
)

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"
MDListItem(
MDListItemLeadingIcon(
icon="account",
),
MDListItemHeadlineText(
text="Headline",
),
MDListItemSupportingText(
text="Supporting text",
),
MDListItemTertiaryText(
text="Tertiary text",
),
MDListItemTrailingIcon(
icon="trash-can-outline",
),
)

List item with trailing check#
MDListItem:
MDListItemLeadingIcon:
icon: "account"
MDListItemHeadlineText:
text: "Headline"
MDListItemSupportingText:
text: "Supporting text"
MDListItemTertiaryText:
text: "Tertiary text"
MDListItemTrailingCheckbox:
MDListItem(
MDListItemLeadingIcon(
icon="account",
),
MDListItemHeadlineText(
text="Headline",
),
MDListItemSupportingText(
text="Supporting text",
),
MDListItemTertiaryText(
text="Tertiary text",
),
MDListItemTrailingCheckbox(
),
)

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
andBackgroundColorBehavior
andRectangularRippleBehavior
andButtonBehavior
andThemableBehavior
andStateLayerBehavior
classes documentation.- divider#
Should I use divider for a list item.
divider
is anBooleanProperty
and defaults to False.
- divider_color#
The divider color in (r, g, b, a) or string format.
divider_color
is aColorProperty
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 aColorProperty
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 aColorProperty
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 aColorProperty
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
andCircularRippleBehavior
andButtonBehavior
andFitImage
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
andBoxLayout
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.
- widget:
>>> 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#
#
See also
Cards contain content and actions about a single subject.

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:

Elevated card
Filled card
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()
from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.button import MDIconButton
from kivymd.uix.card import MDCard
from kivymd.uix.label import MDLabel
from kivymd.uix.relativelayout import MDRelativeLayout
from kivymd.uix.screen import MDScreen
class MyCard(MDCard):
'''Implements a material card.'''
class Example(MDApp):
def build(self):
return (
MDScreen(
MDBoxLayout(
id="box",
adaptive_size=True,
spacing="12dp",
pos_hint={"center_x": 0.5, "center_y": 0.5},
),
theme_bg_color="Custom",
md_bg_color=self.theme_cls.backgroundColor,
)
)
def on_start(self):
super().on_start()
for style in ("elevated", "filled", "outlined"):
self.root.ids.box.add_widget(
MyCard(
MDRelativeLayout(
MDIconButton(
icon="dots-vertical",
pos_hint={"top": 1, "right": 1}
),
MDLabel(
text=style.capitalize(),
adaptive_size=True,
pos=("12dp", "12dp"),
),
),
style=style,
padding="4dp",
size_hint=(None, None),
size=("240dp", "100dp"),
ripple_behavior=True,
)
)
Example().run()

Elevated#
MDCard
style: "elevated"

Filled#
MDCard
style: "filled"

Outlined#
MDCard
style: "outlined"

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

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

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()
from kivymd.app import MDApp
from kivymd.uix.card import (
MDCardSwipe, MDCardSwipeLayerBox, MDCardSwipeFrontBox
)
from kivymd.uix.list import MDList, OneLineListItem
from kivymd.uix.screen import MDScreen
from kivymd.uix.scrollview import MDScrollView
class Example(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
self.theme_cls.primary_palette = "Orange"
return (
MDScreen(
MDScrollView(
MDList(
id="md_list",
padding=0,
),
id="scroll",
scroll_timeout=100,
),
)
)
def on_start(self):
'''Creates a list of cards.'''
super().on_start()
for i in range(20):
self.root.ids.scroll.ids.md_list.add_widget(
MDCardSwipe(
MDCardSwipeLayerBox(),
MDCardSwipeFrontBox(
OneLineListItem(
id="content",
text=f"One-line item {i}",
_no_ripple_effect=True,
)
),
size_hint_y=None,
height="48dp",
)
)
Example().run()

Binding a swipe to one of the sides of the screen#
<SwipeToDeleteItem>
# By default, the parameter is "left"
anchor: "right"

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"

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)
.. code-block:: python
MDCardSwipe(
...
on_swipe_complete=self.on_swipe_complete,
)
def on_swipe_complete(self, instance):
self.root.ids.md_list.remove_widget(instance)
def on_swipe_complete(self, instance):
self.root.ids.box.ids.scroll.ids.md_list.remove_widget(instance)

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)

API - kivymd.uix.card.card
#
- class kivymd.uix.card.card.MDCard(*args, **kwargs)#
Card class.
For more information, see in the
DeclarativeBehavior
andMDAdaptiveWidget
andThemableBehavior
andBackgroundColorBehavior
andCommonElevationBehavior
andRectangularRippleBehavior
andStateLayerBehavior
andButtonBehavior
andBoxLayout
and classes documentation.- ripple_behavior#
Use ripple effect for card.
ripple_behavior
is aBooleanProperty
and defaults to False.
- radius#
Card radius by default.
New in version 1.0.0.
radius
is anVariableListProperty
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 anOptionProperty
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 aColorProperty
and defaults to None.
- on_release(*args) None #
Fired when the button is released (i.e. the touch/click that pressed the button goes away).
- 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 aNumericProperty
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 aStringProperty
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 aStringProperty
and defaults to ‘out_sine’.
- closing_interval#
Interval for closing the front layer.
New in version 1.1.0.
closing_interval
is aNumericProperty
and defaults to 0.
- anchor#
Anchoring screen edge for card. Available options are: ‘left’, ‘right’.
anchor
is aOptionProperty
and defaults to left.
- swipe_distance#
The distance of the swipe with which the movement of navigation drawer begins.
swipe_distance
is aNumericProperty
and defaults to 50.
- opening_time#
The time taken for the card to slide to the
state
‘open’.opening_time
is aNumericProperty
and defaults to 0.2.
- state#
Detailed state. Sets before
state
. Bind tostate
instead ofstatus
. Available options are: ‘closed’, ‘opened’.status
is aOptionProperty
and defaults to ‘closed’.
- max_swipe_x#
If, after the events of
on_touch_up
card position exceeds this value - will automatically execute the methodopen_card
, and if not - will automatically beclose_card
method.max_swipe_x
is aNumericProperty
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 aNumericProperty
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 aOptionProperty
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.
- touch:
- 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.
- 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.
- widget:
>>> 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.
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

Linear progress indicator
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()

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

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

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"

Determinate circular progress indicator#
MDCircularProgressIndicator:
size_hint: None, None
size: "48dp", "48dp"
determinate: True
on_determinate_complete: print(args)

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
andProgressBar
classes documentation.- radius#
Progress line radius.
New in version 1.2.0.
radius
is anVariableListProperty
and defaults to [0, 0, 0, 0].
- reversed#
Reverse the direction the progressbar moves.
reversed
is anBooleanProperty
and defaults to False.
- orientation#
Orientation of progressbar. Available options are: ‘horizontal ‘, ‘vertical’.
orientation
is anOptionProperty
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 anColorProperty
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 anColorProperty
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 anStringProperty
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 anStringProperty
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 anNumericProperty
and defaults to 2.5.
- catching_determinate_duration#
Catching duration.
running_duration
is anNumericProperty
and defaults to 0.8.
- type#
Type of progressbar. Available options are: ‘indeterminate ‘, ‘determinate’.
type
is anOptionProperty
and defaults to None.
- running_indeterminate_transition#
Running transition.
running_indeterminate_transition
is anStringProperty
and defaults to ‘in_cubic’.
- catching_indeterminate_transition#
Catching transition.
catching_indeterminate_transition
is anStringProperty
and defaults to ‘out_quart’.
- running_indeterminate_duration#
Running duration.
running_indeterminate_duration
is anNumericProperty
and defaults to 0.5.
- catching_indeterminate_duration#
Catching duration.
catching_indeterminate_duration
is anNumericProperty
and defaults to 0.8.
- 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
andWidget
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, anddeterminate_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 aBooleanProperty
and defaults to False.
- determinate_time#
Determinate time value.
determinate_time
is aNumericProperty
and defaults to 2.
- line_width#
Progress line width of indicator.
line_width
is aNumericProperty
and defaults to dp(2.25).
- active#
Use
active
to start or stop the indicator.active
is aBooleanProperty
and defaults to True.
- color#
Indicator color in (r, g, b, a) or string format.
color
is aColorProperty
and defaults to None.
- palette#
A set of colors. Changes with each completed indicator cycle.
palette
is aListProperty
and defaults to [].
- on__rotation_angle(*args)#
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()
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.card import MDCard
from kivymd.uix.fitimage import FitImage
from kivymd.uix.screen import MDScreen
class Example(MDApp):
def build(self):
return (
MDScreen(
MDBoxLayout(
FitImage(
source="image.png",
size_hint_y=0.35,
pos_hint={"top": 1},
radius=(dp(36), dp(36), 0, 0),
),
radius=dp(36),
md_bg_color=self.theme_cls.onSurfaceVariantColor,
pos_hint={"center_x": 0.5, "center_y": 0.5},
size_hint=(0.4, 0.8),
),
)
)
Example().run()

API - kivymd.uix.fitimage.fitimage
#
- class kivymd.uix.fitimage.fitimage.FitImage(**kwargs)#
Fit image class.
For more information, see in the
AsyncImage
andStencilBehavior
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 aOptionProperty
and defaults to ‘cover’.
Badge#
#
New in version 2.0.0.
See also
Badges show notifications, counts, or status information on navigation items and icons.

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

API - kivymd.uix.badge.badge
#
Snackbar#
#
See also
Snackbars provide brief messages about app processes at the bottom of the screen.

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

Container
Supporting text
Action (optional)
Icon (optional close affordance)
Anatomy#

Configurations#
1. Single line#

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#

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()
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
andBoxLayout
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.
- widget:
>>> 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
andMDCard
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 aNumericProperty
and defaults to 3.
- auto_dismiss#
Whether to use automatic closing of the snackbar or not.
auto_dismiss
is aBooleanProperty
and defaults to True.
- radius#
Snackbar radius.
radius
is aListProperty
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 aColorProperty
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.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
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.

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
.
- 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
.
Text fields#
#
See also
Text fields let users enter text into a UI.

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

Filled text field
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#

Available types of text fields#
Filled mode#
MDTextField:
mode: "filled"

Outlined mode#
MDTextField:
mode: "outlined"

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()
from kivymd.uix.textfield import (
MDTextField,
MDTextFieldLeadingIcon,
MDTextFieldHintText,
MDTextFieldHelperText,
MDTextFieldTrailingIcon,
MDTextFieldMaxLengthText,
)
from kivymd.uix.screen import MDScreen
from kivymd.app import MDApp
class Example(MDApp):
def build(self):
self.theme_cls.primary_palette = "Olive"
return MDScreen(
MDTextField(
MDTextFieldLeadingIcon(
icon="account",
),
MDTextFieldHintText(
text="Hint text",
),
MDTextFieldHelperText(
text="Helper text",
mode="persistent",
),
MDTextFieldTrailingIcon(
icon="information",
),
MDTextFieldMaxLengthText(
max_text_length=10,
),
mode="outlined",
size_hint_x=None,
width="240dp",
pos_hint={"center_x": 0.5, "center_y": 0.5},
),
md_bg_color=self.theme_cls.backgroundColor,
)
Example().run()

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.
- 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 anObjectProperty
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 anListProperty
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 anOptionProperty
and defaults to None.
- 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"
text_color_normal
is anColorProperty
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"
text_color_focus
is anColorProperty
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"
On error#
MDTextField: mode: "filled" MDTextFieldHelperText: text: "Helper text" mode: "on_error" MDTextFieldMaxLengthText: max_text_length: 5
Persistent#
MDTextField: mode: "filled" MDTextFieldHelperText: text: "Helper text" mode: "persistent"
mode
is anOptionProperty
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
max_text_length
is anNumericProperty
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"
- 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"
icon_color_normal
is anColorProperty
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"
icon_color_focus
is anColorProperty
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"
- 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"
- class kivymd.uix.textfield.textfield.MDTextField(*args, **kwargs)#
Textfield class.
For more information, see in the
DeclarativeBehavior
andBackgroundColorBehavior
andThemableBehavior
andTextInput
andValidator
andAutoFormatTelephoneNumber
andStateLayerBehavior
classes documentation.- font_style#
Name of the style for the input text.
New in version 2.0.0.
See also
font_style
is anStringProperty
and defaults to ‘Body’.
- role#
Role of font style.
New in version 2.0.0.
See also
role
is anStringProperty
and defaults to ‘large’.
- mode#
Text field mode. Available options are: ‘outlined’, ‘filled’.
mode
is anOptionProperty
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 anColorProperty
and defaults to None.
- error#
If True, then the text field goes into error mode.
error
is anBooleanProperty
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"
text_color_normal
is anColorProperty
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"
text_color_focus
is anColorProperty
and defaults to None.
- radius#
The corner radius for a text field in filled/outlined mode.
radius
is aVariableListProperty
and defaults to [dp(4), dp(4), 0, 0].
- required#
Required text. If True then the text field requires text.
required
is anBooleanProperty
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"
line_color_normal
is anColorProperty
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"
line_color_focus
is anColorProperty
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"
fill_color_normal
is anColorProperty
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"
fill_color_focus
is anColorProperty
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"
max_height
is aNumericProperty
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 aStringProperty
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"
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()
validator
is anOptionProperty
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.
- widget:
>>> 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_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.
DropdownItem#
#

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
andThemableBehavior
andButtonBehavior
andBoxLayout
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.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
Appbar#
#

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

Center-aligned
Small
Medium
Large
Note
KivyMD does not provide a Center-aligned type panel. But you can easily create this pit panel yourself (read the documentation below).
Usage#
MDTopAppBar:
type: "small"
MDTopAppBarLeadingButtonContainer:
MDActionTopAppBarButton:
icon: "menu"
MDTopAppBarTitle:
text: "AppBar Center-aligned"
pos_hint: {"center_x": .5}
MDTopAppBarTrailingButtonContainer:
MDActionTopAppBarButton:
icon: "account-circle-outline"
Anatomy#

Configurations#
1. Center-aligned#
MDScreen:
md_bg_color: self.theme_cls.secondaryContainerColor
MDTopAppBar:
type: "small"
size_hint_x: .8
pos_hint: {"center_x": .5, "center_y": .5}
MDTopAppBarLeadingButtonContainer:
MDActionTopAppBarButton:
icon: "menu"
MDTopAppBarTitle:
text: "AppBar small"
pos_hint: {"center_x": .5}
MDTopAppBarTrailingButtonContainer:
MDActionTopAppBarButton:
icon: "account-circle-outline"

2. Small#
MDScreen:
md_bg_color: self.theme_cls.secondaryContainerColor
MDTopAppBar:
type: "small"
size_hint_x: .8
pos_hint: {"center_x": .5, "center_y": .5}
MDTopAppBarLeadingButtonContainer:
MDActionTopAppBarButton:
icon: "arrow-left"
MDTopAppBarTitle:
text: "AppBar small"
MDTopAppBarTrailingButtonContainer:
MDActionTopAppBarButton:
icon: "attachment"
MDActionTopAppBarButton:
icon: "calendar"
MDActionTopAppBarButton:
icon: "dots-vertical"

3. Medium#
MDTopAppBar:
type: "medium"

4. Large#
MDTopAppBar:
type: "large"

BottomAppBar#

from kivy.lang import Builder
from kivymd.app import MDApp
KV = '''
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDBottomAppBar:
MDFabBottomAppBarButton:
icon: "plus"
'''
class Example(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
return Builder.load_string(KV)
Example().run()

Add action items#
#:import MDActionBottomAppBarButton kivymd.uix.appbar.MDActionBottomAppBarButton
MDScreen:
MDBottomAppBar:
action_items:
[
MDActionBottomAppBarButton(icon="gmail"),
MDActionBottomAppBarButton(icon="label-outline"),
MDActionBottomAppBarButton(icon="bookmark"),
]

Change action items#
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.appbar import MDActionBottomAppBarButton
KV = '''
#:import MDActionBottomAppBarButton kivymd.uix.appbar.MDActionBottomAppBarButton
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDBottomAppBar:
id: bottom_appbar
action_items:
[
MDActionBottomAppBarButton(icon="gmail"),
MDActionBottomAppBarButton(icon="bookmark"),
]
MDFabBottomAppBarButton:
icon: "plus"
on_release: app.change_actions_items()
'''
class Example(MDApp):
def change_actions_items(self):
self.root.ids.bottom_appbar.action_items = [
MDActionBottomAppBarButton(icon="magnify"),
MDActionBottomAppBarButton(icon="trash-can-outline"),
MDActionBottomAppBarButton(icon="download-box-outline"),
]
def build(self):
self.theme_cls.theme_style = "Dark"
return Builder.load_string(KV)
Example().run()

A practical example#
import asynckivy
from kivy.clock import Clock
from kivy.lang import Builder
from kivy.properties import StringProperty, BooleanProperty, ObjectProperty
from kivy.uix.behaviors import FocusBehavior
from kivy.uix.recycleboxlayout import RecycleBoxLayout
from kivy.uix.recycleview.layout import LayoutSelectionBehavior
from kivy.uix.recycleview.views import RecycleDataViewBehavior
from kivymd.uix.appbar import MDActionBottomAppBarButton
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.app import MDApp
from faker import Faker # pip install Faker
KV = '''
#:import MDFabBottomAppBarButton kivymd.uix.appbar.MDFabBottomAppBarButton
<UserCard>
orientation: "vertical"
adaptive_height: True
md_bg_color: "#373A22" if self.selected else "#1F1E15"
radius: 16
padding: 0, 0, 0, "16dp"
MDListItem:
theme_bg_color: "Custom"
md_bg_color: root.md_bg_color
radius: root.radius
ripple_effect: False
MDListItemLeadingAvatar:
source: root.avatar
# radius: self.height / 2
MDListItemHeadlineText:
text: root.name
theme_text_color: "Custom"
text_color: "#8A8D79"
MDListItemSupportingText:
text: root.time
theme_text_color: "Custom"
text_color: "#8A8D79"
MDLabel:
text: root.text
adaptive_height: True
theme_text_color: "Custom"
text_color: "#8A8D79"
padding_x: "16dp"
shorten: True
shorten_from: "right"
Widget:
MDFloatLayout:
md_bg_color: "#151511"
RecycleView:
id: card_list
viewclass: "UserCard"
SelectableRecycleGridLayout:
orientation: 'vertical'
spacing: "16dp"
padding: "16dp"
default_size: None, dp(120)
default_size_hint: 1, None
size_hint_y: None
height: self.minimum_height
multiselect: True
touch_multiselect: True
MDBottomAppBar:
id: bottom_appbar
scroll_cls: card_list
allow_hidden: True
theme_bg_color: "Custom"
md_bg_color: "#232217"
MDFabBottomAppBarButton:
id: fab_button
icon: "plus"
theme_bg_color: "Custom"
md_bg_color: "#373A22"
theme_icon_color: "Custom"
icon_color: "#ffffff"
'''
class UserCard(RecycleDataViewBehavior, MDBoxLayout):
name = StringProperty()
time = StringProperty()
text = StringProperty()
avatar = StringProperty()
callback = ObjectProperty(lambda x: x)
index = None
selected = BooleanProperty(False)
selectable = BooleanProperty(True)
def refresh_view_attrs(self, rv, index, data):
self.index = index
return super().refresh_view_attrs(rv, index, data)
def on_touch_down(self, touch):
if super().on_touch_down(touch):
return True
if self.collide_point(*touch.pos) and self.selectable:
Clock.schedule_once(self.callback)
return self.parent.select_with_touch(self.index, touch)
def apply_selection(self, rv, index, is_selected):
self.selected = is_selected
rv.data[index]["selected"] = is_selected
class SelectableRecycleGridLayout(
FocusBehavior, LayoutSelectionBehavior, RecycleBoxLayout
):
pass
class BottomAppBarButton(MDActionBottomAppBarButton):
theme_icon_color = "Custom"
icon_color = "#8A8D79"
class Example(MDApp):
selected_cards = False
def build(self):
return Builder.load_string(KV)
def on_tap_card(self, *args):
datas = [data["selected"] for data in self.root.ids.card_list.data]
if True in datas and not self.selected_cards:
self.root.ids.bottom_appbar.action_items = [
BottomAppBarButton(icon="gmail"),
BottomAppBarButton(icon="label-outline"),
BottomAppBarButton(icon="bookmark"),
]
self.root.ids.fab_button.icon = "pencil"
self.selected_cards = True
else:
if len(list(set(datas))) == 1 and not list(set(datas))[0]:
self.selected_cards = False
if not self.selected_cards:
self.root.ids.bottom_appbar.action_items = [
BottomAppBarButton(icon="magnify"),
BottomAppBarButton(icon="trash-can-outline"),
BottomAppBarButton(icon="download-box-outline"),
]
self.root.ids.fab_button.icon = "plus"
def on_start(self):
async def generate_card():
for i in range(10):
await asynckivy.sleep(0)
self.root.ids.card_list.data.append(
{
"name": fake.name(),
"time": fake.date(),
"avatar": fake.image_url(),
"text": fake.text(),
"selected": False,
"callback": self.on_tap_card,
}
)
super().on_start()
self.on_tap_card()
fake = Faker()
Clock.schedule_once(lambda x: asynckivy.start(generate_card()))
Example().run()

API break#
1.2.0 version#
MDTopAppBar:
type_height: "large"
headline_text: "Headline"
left_action_items: [["arrow-left", lambda x: x]]
right_action_items:
[ ["attachment", lambda x: x], ["calendar", lambda x: x], ["dots-vertical", lambda x: x], ]
anchor_title: "left"
2.0.0 version#
MDTopAppBar:
type: "large"
MDTopAppBarLeadingButtonContainer:
MDActionTopAppBarButton:
icon: "arrow-left"
MDTopAppBarTitle:
text: "AppBar small"
MDTopAppBarTrailingButtonContainer:
MDActionTopAppBarButton:
icon: "attachment"
MDActionTopAppBarButton:
icon: "calendar"
MDActionTopAppBarButton:
icon: "dots-vertical"
API - kivymd.uix.appbar.appbar
#
- class kivymd.uix.appbar.appbar.MDFabBottomAppBarButton(**kwargs)#
Implements a floating action button (FAB) for a bar with type ‘bottom’.
For more information, see in the
MDFabButton
andRotateBehavior
andScaleBehavior
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 aColorProperty
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.
- 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
andBoxLayout
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
andBoxLayout
classes documentation.
- class kivymd.uix.appbar.appbar.MDTopAppBar(*args, **kwargs)#
Top app bar class.
For more information, see in the
DeclarativeBehavior
andThemableBehavior
andCommonElevationBehavior
andBackgroundColorBehavior
andBoxLayout
andWindowController
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 anBooleanProperty
and defaults to False.
- type#
Bar height type.
New in version 1.0.0.
Available options are: ‘medium’, ‘large’, ‘small’.
type_height
is anOptionProperty
and defaults to ‘small’.
- 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.
- widget:
>>> 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
andThemableBehavior
andBackgroundColorBehavior
andCommonElevationBehavior
andFloatLayout
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 anListProperty
and defaults to [].
- animation#
# TODO: add description. # FIXME: changing the value does not affect anything.
New in version 1.2.0.
animation
is anBooleanProperty
and defaults to True.
- show_transition#
Type of button display transition.
New in version 1.2.0.
show_transition
is aStringProperty
and defaults to ‘linear’.
- hide_transition#
Type of button hidden transition.
New in version 1.2.0.
hide_transition
is aStringProperty
and defaults to ‘in_back’.
- hide_duration#
Duration of button hidden transition.
New in version 1.2.0.
hide_duration
is aNumericProperty
and defaults to 0.2.
- show_duration#
Duration of button display transition.
New in version 1.2.0.
show_duration
is aNumericProperty
and defaults to 0.2.
- scroll_cls#
Widget inherited from the
ScrollView
class. The value must be set if theallow_hidden
parameter is True.New in version 1.2.0.
scroll_cls
is aObjectProperty
and defaults to None.
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 aBooleanProperty
and defaults to False.
Is the panel currently hidden.
New in version 1.2.0.
bar_is_hidden
is aBooleanProperty
and defaults to False.
- button_centering_animation(button: MDActionBottomAppBarButton | MDFabBottomAppBarButton) None #
Animation of centering buttons for
MDActionOverFlowButton
,MDActionBottomAppBarButton
andMDFabBottomAppBarButton
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_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.
- widget:
>>> 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#
#
See also
Dialogs provide important prompts in a user flow.

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#

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

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

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

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

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

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

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

API - kivymd.uix.dialog.dialog
#
- class kivymd.uix.dialog.dialog.MDDialog(*args, **kwargs)#
Dialog class.
For more information, see in the
MDCard
andMotionDialogBehavior
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 anNumericProperty
and defaults to dp(48).
- radius#
Dialog corners rounding value.
radius
is anVariableListProperty
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 aColorProperty
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 aBooleanProperty
and defaults to True.
- 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.
- widget:
>>> 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_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.
- touch:
- 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.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
andBoxLayout
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
andBoxLayout
classes documentation.
SelectionControls#
#
Selection controls allow the user to select options.
KivyMD provides the following selection controls classes for use:
MDCheckbox#

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

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

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

MDSwitch#

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

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
andCircularRippleBehavior
andScaleBehavior
andToggleButtonBehavior
andMDIcon
classes documentation.- active#
Indicates if the checkbox is active or inactive.
active
is aBooleanProperty
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 aStringProperty
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 aStringProperty
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 aStringProperty
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 aStringProperty
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"
color_active
is aColorProperty
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"
color_inactive
is aColorProperty
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 aColorProperty
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 aColorProperty
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 aColorProperty
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 aColorProperty
and defaults to None.
- update_icon(*args) None #
Fired when the values of
checkbox_icon_normal
andcheckbox_icon_down
andradio_icon_normal
andgroup
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.
- touch:
- 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
andMDFloatLayout
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 aColorProperty
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 aBooleanProperty
and defaults to True.
- active#
Indicates if the switch is active or inactive.
active
is aBooleanProperty
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"
icon_active
is aStringProperty
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"
icon_inactive
is aStringProperty
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"
icon_active_color
is aColorProperty
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"
icon_inactive_color
is aColorProperty
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"
thumb_color_active
is anColorProperty
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"
thumb_color_inactive
is anColorProperty
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
thumb_color_disabled
is anColorProperty
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"
track_color_active
is anColorProperty
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"
track_color_inactive
is anColorProperty
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
track_color_disabled
is anColorProperty
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 anColorProperty
and defaults to None.
- set_icon(instance_switch, icon_value: str) None #
Fired when the values of
icon_active
andicon_inactive
change.
TimePicker#
#
See also
Time pickers help users select and set a specific time.

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

Vertical dial time picker
Horizontal dial time picker
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.

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.

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

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.

def show_time_picker(self):
MDTimePickerInput().open()
Events#
on_edit event#

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#

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#

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#

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#

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#

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#

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#

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#

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
andMotionTimePickerBehavior
andBoxLayout
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 anStringProperty
and defaults to ‘12’.
- minute#
Current minute.
minute
is anStringProperty
and defaults to 0.
- am_pm#
Current AM/PM mode.
am_pm
is anOptionProperty
and defaults to ‘am’.
- animation_duration#
Duration of the animations.
animation_duration
is anNumericProperty
and defaults to 0.2.
- animation_transition#
Transition type of the animations.
animation_transition
is anStringProperty
and defaults to ‘out_quad’.
- time#
Returns the current time object.
time
is anObjectProperty
and defaults to None.
- headline_text#
Headline text.
headline_text
is anStringProperty
and defaults to ‘Select time’.
- text_button_ok#
The text of the confirmation button.
text_button_ok
is aStringProperty
and defaults to ‘Ok’.
- text_button_cancel#
The text of the cancel button.
text_button_cancel
is aStringProperty
and defaults to ‘Cancel’.
- radius#
Container radius.
radius
is anVariableListProperty
and defaults to [dp(16), dp(16), dp(16), dp(16)].
- is_open#
Is the date picker dialog open.
is_open
is aBooleanProperty
and defaults to False.
- scrim_color#
Color for scrim in (r, g, b, a) or string format.
scrim_color
is aColorProperty
and defaults to [0, 0, 0, 0.5].
- set_time(time_obj: datetime.time) None #
Manually set time dialog with the specified time.
- 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.
- touch:
- 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.pickers.timepicker.timepicker.MDTimePickerInput(**kwargs)#
Implements input time picker.
New in version 2.0.0.
For more information, see in the
CommonElevationBehavior
andMDBaseTimePicker
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
andMDBaseTimePicker
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
andMDBaseTimePicker
classes documentation.
DatePicker#
#
See also
Date pickers let people select a date, or a range of dates.

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

Docked date picker
Modal date picker
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.

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.

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.

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:

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

Setting the date range manually#
def show_modal_date_picker(self, *args):
MDModalInputDatePicker(mode="range").open()

Events#
on_edit event#

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#

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#

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#

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#

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#

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#

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
andMotionDatePickerBehavior
andBoxLayout
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 anNumericProperty
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 anNumericProperty
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 anNumericProperty
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 anNumericProperty
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 anNumericProperty
and defaults to 2121.
- mode#
Dialog type. Available options are: ‘picker’, ‘range’.
mode
is anOptionProperty
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 anObjectProperty
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 anObjectProperty
and defaults to None.
- radius#
Container radius.
radius
is anVariableListProperty
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 aColorProperty
and defaults to [0, 0, 0, 0.5].
- supporting_text#
Supporting text.
supporting_text
is aStringProperty
and defaults to ‘Select date’.
- text_button_ok#
The text of the confirmation button.
text_button_ok
is aStringProperty
and defaults to ‘Ok’.
- text_button_cancel#
The text of the cancel button.
text_button_cancel
is aStringProperty
and defaults to ‘Cancel’.
- mark_today#
Highlights the current day.
mark_today
is aBooleanProperty
and defaults to True.
- is_open#
Is the date picker dialog open.
is_open
is aBooleanProperty
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.
- change_month(operation: str) None #
Called when “chevron-left” and “chevron-right” buttons are pressed. Switches the calendar to the previous/next month.
- 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.
- touch:
- 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.pickers.datepicker.datepicker.MDDockedDatePicker(**kwargs)#
Implements docked date picker.
New in version 2.0.0.
For more information, see in the
CommonElevationBehavior
andMDBaseDatePicker
classes documentation.Generates a list for the month or year selection menu.
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
andMDBaseDatePicker
classes documentation.
- 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
andMDBaseDatePicker
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 anOptionProperty
and defaults to None.
- default_input_date#
If true, the current date will be set in the input field.
default_input_date
is aBooleanProperty
and defaults to True.
- error_text#
Error text when the date entered by the user is not valid.
error_text
is aStringProperty
and defaults to ‘Invalid date format’.
- supporting_input_text#
Auxiliary text when entering the date manually.
supporting_input_text
is aStringProperty
and defaults to ‘Enter date’.
- 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
.
Divider#
#
New in version 2.0.0.
See also
Dividers are thin lines that group content in lists or other containers.

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.

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

VerticalDivider#
A vertical divider can be used to arrange content on a larger screen, such as separating paragraph text from video or imagery media.

MDDivider:
size_hint_y: .5
orientation: "vertical"

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 aColorProperty
and defaults to None.
- divider_width#
Divider width.
divider_width
is anNumericProperty
and defaults to dp(1).
ImageList#
#
See also
Image lists display a collection of images in an organized grid.

Usage#
MDSmartTile:
[...]
MDSmartTileImage:
[...]
MDSmartTileOverlayContainer:
[...]
# Content
[...]
Anatomy#

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

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
andButtonBehavior
andFitImage
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.
overlay_mode
is aOptionProperty
and defaults to ‘footer’.
- overlap#
Determines if the header/footer overlaps on top of the image or not.
overlap
is aBooleanProperty
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.
- widget:
>>> 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#
#

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

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 anNumericProperty
and defaults to 20dp.
- transition_duration#
Duration of switching between
MDSwiperItem
.transition_duration
is anNumericProperty
and defaults to 0.2.
- size_duration#
Duration of changing the size of
MDSwiperItem
.transition_duration
is anNumericProperty
and defaults to 0.2.
- size_transition#
The type of animation used for changing the size of
MDSwiperItem
.size_transition
is anStringProperty
and defaults to out_quad.
- swipe_transition#
The type of animation used for swiping.
swipe_transition
is anStringProperty
and defaults to out_quad.
- swipe_distance#
Distance to move before swiping the
MDSwiperItem
.swipe_distance
is anNumericProperty
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 ofMDSwiperItem
. So by decreasing thewidth_mult
the width ofMDSwiperItem
increases and vice versa.width_mult
is anNumericProperty
and defaults to 3.
- swipe_on_scroll#
Wheter to swipe on mouse wheel scrolling or not.
swipe_on_scroll
is anBooleanProperty
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.
- widget:
>>> 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.
- widget:
>>> 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.
- touch:
- 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
andMDScrollView
class documentation.- root_layout#
The spinner will be attached to this layout.
root_layout
is aObjectProperty
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 aObjectProperty
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 aColorProperty
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 aColorProperty
and defaults to None.
- show_transition#
Transition of the spinner’s opening.
New in version 1.2.0.
show_transition
is aStringProperty
and defaults to ‘out_elastic’.
- show_duration#
Duration of the spinner display.
New in version 1.2.0.
show_duration
is aNumericProperty
and defaults to 0.8.
- hide_transition#
Transition of hiding the spinner.
New in version 1.2.0.
hide_transition
is aStringProperty
and defaults to ‘out_elastic’.
- hide_duration#
Duration of hiding the spinner.
New in version 1.2.0.
hide_duration
is aNumericProperty
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.
Tooltip#
#
See also
Tooltips display brief labels or messages.

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:
Plain tooltip
Rich tooltip

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

The anatomy of a plain tooltip#

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

The anatomy of a plain tooltip#

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 anBoundedNumericProperty
and defaults to 0, min of 0 & max of 4.
- shift_y#
Y-offset of tooltip to the top.
shift_y
is anNumericProperty
and defaults to 0.
- shift_right#
Shifting the tooltip to the right.
New in version 1.0.0.
shift_right
is anNumericProperty
and defaults to 0.
- shift_left#
Shifting the tooltip to the left.
New in version 1.0.0.
shift_left
is anNumericProperty
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.
- animation_tooltip_dismiss(*args) None #
Animation of closing tooltip on the screen.
New in version 1.0.0.
- add_widget(widget, *args, **kwargs)#
Add a new widget as a child of this widget.
- class kivymd.uix.tooltip.tooltip.MDTooltipPlain(*args, **kwargs)#
Tooltip plain class.
New in version 2.0.0.
For more information, see in the
MDLabel
andScaleBehavior
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.
- class kivymd.uix.tooltip.tooltip.MDTooltipRich(*args, **kwargs)#
Tooltip rich class.
New in version 2.0.0.
For more information, see in the
DeclarativeBehavior
andThemableBehavior
andBackgroundColorBehavior
andCommonElevationBehavior
andScaleBehavior
andStateLayerBehavior
andBoxLayout
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 aBooleanProperty
and defaults to True.
Chip#
#
See also
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.

Usage#
MDChip:
MDChipLeadingAvatar: # MDChipLeadingIcon
MDChipText:
MDChipTrailingIcon:
Anatomy#

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()
from kivymd.app import MDApp
from kivymd.uix.chip import MDChip, MDChipText
from kivymd.uix.screen import MDScreen
class Example(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
return (
MDScreen(
MDChip(
MDChipText(
text="MDChip"
),
pos_hint={"center_x": .5, "center_y": .5},
)
)
)
Example().run()

The following types of chips are available:#

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.

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

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.

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

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

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

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.

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

Suggestion#
Suggestion chips help narrow a user’s intent by presenting dynamically generated suggestions, such as possible responses or search filters.

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

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
andScaleBehavior
andButtonBehavior
andMDIcon
classes documentation.
- class kivymd.uix.chip.chip.MDChipLeadingIcon(**kwargs)#
Implements the leading icon for the chip.
For more information, see in the
CircularRippleBehavior
andScaleBehavior
andButtonBehavior
andMDIcon
classes documentation.
- class kivymd.uix.chip.chip.MDChipTrailingIcon(**kwargs)#
Implements the trailing icon for the chip.
For more information, see in the
CircularRippleBehavior
andScaleBehavior
andButtonBehavior
andMDIcon
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 aColorProperty
and defaults to None.
- class kivymd.uix.chip.chip.MDChip(*args, **kwargs)#
Chip class.
For more information, see in the
MDBoxLayout
andRectangularRippleBehavior
andButtonBehavior
andCommonElevationBehavior
andTouchBehavior
classes documentation.- radius#
Chip radius.
radius
is anVariableListProperty
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 anOptionProperty
and defaults to ‘suggestion’.
- active#
Whether the check is marked or not.
New in version 1.0.0.
active
is anBooleanProperty
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 anColorProperty
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 anColorProperty
and defaults to None.
- 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.
- widget:
>>> 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#
#
See also
Bottom sheets are surfaces containing supplementary content that are anchored to the bottom of the screen.

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.

Standard bottom sheets are elevated above the main UI region so their visibility is not affected by panning or scrolling.
Modal#
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.

Tapping the scrim dismisses a modal bottom sheet.

Add elements to MDBottomSheetDragHandleTitle
class#
MDBottomSheet:
MDBottomSheetDragHandle:
MDBottomSheetDragHandleTitle:
text: "MDBottomSheet"
adaptive_height: True
pos_hint: {"center_y": .5}
MDBottomSheetDragHandleButton:
icon: "close"

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"
drag_handle_color
is anColorProperty
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.
- widget:
>>> 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 aOptionProperty
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.
- widget:
>>> 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#
#
See also
Sliders allow users to make selections from a range of values.

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

Continuous slider
Discrete slider
Usage#
MDSlider(
MDSliderHandle(
),
MDSliderValueLabel(
),
step=10,
value=50,
)
MDSlider:
step: 10
value: 50
MDSliderHandle:
MDSliderValueLabel:
Anatomy#

API - kivymd.uix.slider.slider
#
- class kivymd.uix.slider.slider.MDSlider(*args, **kwargs)#
Slider class.
For more information, see in the
DeclarativeBehavior
andThemableBehavior
andSlider
classes documentation.- track_active_width#
Width of the active track.
New in version 2.0.0.
track_active_width
is anNumericProperty
and defaults to dp(4).
- track_inactive_width#
Width of the inactive track.
New in version 2.0.0.
track_inactive_width
is anNumericProperty
and defaults to dp(4).
- step_point_size#
Step point size.
New in version 2.0.0.
step_point_size
is anNumericProperty
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 anColorProperty
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 anColorProperty
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 anColorProperty
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 anColorProperty
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 anNumericProperty
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 anNumericProperty
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 anStringProperty
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 anStringProperty
and defaults to ‘out_circ’.
- handle_anim_transition#
Handle animation type.
New in version 2.0.0.
handle_anim_transition
is anStringProperty
and defaults to ‘out_circ’.
- handle_anim_duration#
Handle animation duration.
New in version 2.0.0.
handle_anim_duration
is anNumericProperty
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.
- widget:
>>> 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_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.
- touch:
- 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.
- class kivymd.uix.slider.slider.MDSliderHandle(**kwargs)#
Handle class.
New in version 2.0.0.
For more information, see in the
ThemableBehavior
andBackgroundColorBehavior
andFocusBehavior
andWidget
classes documentation.- radius#
Handle radius.
radius
is anVariableListProperty
and defaults to [dp(10), dp(10), dp(10), dp(10)].
- size#
Handle size.
size
is anListProperty
and defaults to [dp(20), dp(20)].
- state_layer_size#
Handle state layer size.
state_layer_size
is anListProperty
and defaults to [dp(40), dp(40)].
- state_layer_color#
Handle state layer color.
state_layer_color
is anColorProperty
and defaults to None.
- 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 anListProperty
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

Note
This widget is a modification of the silverappbar.py module.
Usage#
MDScreen:
MDSliverAppbar:
MDTopAppBar:
[...]
MDSliverAppbarHeader:
# Custom content.
[...]
# Custom list.
MDSliverAppbarContent:
Anatomy#

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
andBoxLayout
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 anColorProperty
and defaults to None.
- max_height#
Distance from top of screen to start of custom list content.
MDSliverAppbar: max_height: "200dp"
max_height
is anNumericProperty
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
MDSliverAppbar: hide_appbar: True
hide_appbar
is anBooleanProperty
and defaults to None.
- radius#
Box radius for custom item list.
MDSliverAppbar: radius: 20
radius
is anVariableListProperty
and defaults to [20].
- max_opacity#
Maximum background transparency value for the
MDSliverAppbarHeader
class.MDSliverAppbar: max_opacity: .5
max_opacity
is anNumericProperty
and defaults to 1.
- on_scroll_content(instance: object = None, value: float = 1.0, direction: str = 'up')#
Fired when the list of custom content is being scrolled.
- Parameters:
instance –
MDSliverAppbar
value – see
scroll_y
direction – scroll direction: ‘up/down’
- 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.
- widget:
>>> 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)#
Tabs#
#
See also
Tabs organize content across different screens, data sets, and other interactions.

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

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

Anatomy primary tabs#

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#

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

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

Tap a tab#
Navigate to a tab by tapping on it.

Swipe within the content area#
To navigate between tabs, users can swipe left or right within the content area.

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 anBooleanProperty
and defaults to False.
- 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
andBoxLayout
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.
- widget:
>>> 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
andThemableBehavior
andBoxLayout
classes documentation.- Events:
- on_tab_switch
Fired when switching tabs.
- md_bg_color#
The background color of the widget.
md_bg_color
is anColorProperty
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 anBooleanProperty
and defaults to False.
- allow_stretch#
Whether to stretch tabs to the width of the panel.
allow_stretch
is anBooleanProperty
and defaults to True.
- lock_swiping#
If True - disable switching tabs by swipe.
lock_swiping
is anBooleanProperty
and defaults to False.
- anim_duration#
Duration of the slide animation.
anim_duration
is anNumericProperty
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 anBooleanProperty
and defaults to True.
- indicator_radius#
Radius of the tab indicator.
New in version 2.0.0.
indicator_radius
is anVariableListProperty
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 anNumericProperty
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 anNumericProperty
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 anStringProperty
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 anAliasProperty
.
- 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 anObjectProperty
and default to None.
- indicator#
It is the
SmoothRoundedRectangle
instruction reference of the tab indicator.indicator
is anAliasProperty
.
- 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.
- widget:
>>> 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_slide_progress(*args) None #
This event is deployed every available frame while the tab is scrolling.
- on_carousel_index(instance: MDTabsCarousel, value: int) None #
Fired when the Tab index have changed. This event is deployed by the builtin carousel of the class.
- 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
andAnchorLayout
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.
- widget:
>>> 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 anVariableListProperty
and defaults to [0, 0, 0, 0].
- indicator_height#
Height of the tab indicator.
indicator_height
is anNumericProperty
and defaults to ‘2dp’.
Label#
#
The MDLabel widget is for rendering text.

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()
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen
from kivymd.uix.label import MDLabel
class Test(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
return (
MDScreen(
MDLabel(
text="MDLabel",
halign="center",
),
md_bg_color=self.theme_cls.backgroundColor,
)
)
Test().run()

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"

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"

MDLabel:
text: "Display, role - 'small'"
font_style: "Display"
role: "small"

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

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()
from kivy.clock import Clock
from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.uix.screen import MDScreen
class Example(MDApp):
def on_start(self):
def on_start(dt):
self.root.md_bg_color = self.theme_cls.backgroundColor
super().on_start()
Clock.schedule_once(on_start)
def build(self):
self.theme_cls.theme_style = "Dark"
return (
MDScreen(
MDLabel(
adaptive_size=True,
pos_hint={"center_x": 0.5, "center_y": 0.5},
text="Do a double click on me",
allow_selection=True,
padding=("4dp", "4dp"),
),
)
)
Example().run()

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()
from kivy.lang.builder import Builder
from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.uix.screen import MDScreen
class Example(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
self.theme_cls.primary_palette = "Orange"
return (
MDScreen(
MDLabel(
id="label",
adaptive_size=True,
pos_hint={"center_x": .5, "center_y": .5},
text="MDLabel",
allow_selection=True,
allow_copy=True,
padding=("4dp", "4dp"),
)
)
)
def on_start(self):
super().on_start()
self.root.ids.label.bind(on_copy=self.on_copy)
def on_copy(self, instance_label: MDLabel):
print("The text is copied to the clipboard")
Example().run()
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"

MDIcon with badge icon#
MDIcon:
icon: "gmail"
MDBadge:
text: "10+"

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

API - kivymd.uix.label.label
#
- class kivymd.uix.label.label.MDLabel(*args, **kwargs)#
Label class.
For more information, see in the
DeclarativeBehavior
andThemableBehavior
andBackgroundColorBehavior
andLabel
andMDAdaptiveWidget
andTouchBehavior
andStateLayerBehavior
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 anStringProperty
and defaults to ‘Body’.
- role#
Role of font style.
New in version 2.0.0.
Available options are: ‘large’, ‘medium’, ‘small’.
role
is anStringProperty
and defaults to ‘large’.
- text#
Text of the label.
text
is anStringProperty
and defaults to ‘’.
- text_color#
Label text color in (r, g, b, a) or string format.
text_color
is anColorProperty
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 anBooleanProperty
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 anBooleanProperty
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 anColorProperty
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 anColorProperty
and defaults to None.
- is_selected#
Is the label text highlighted.
New in version 1.2.0.
is_selected
is anBooleanProperty
and defaults to False.
- radius#
Label radius.
radius
is anVariableListProperty
and defaults to [0, 0, 0, 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.
- 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 anStringProperty
and defaults to ‘blank’.
- source#
Path to icon.
source
is anStringProperty
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 aColorProperty
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 aColorProperty
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.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
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#
Behaviors#
Motion#
#
Use motion to make a UI expressive and easy to use.

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 aStringProperty
and defaults to ‘linear’.
- show_duration#
Duration of widget display transition.
show_duration
is aNumericProperty
and defaults to 0.2.
- hide_transition#
The type of transition of the widget closing.
hide_transition
is aStringProperty
and defaults to ‘linear’.
- hide_duration#
Duration of widget closing transition.
hide_duration
is aNumericProperty
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 aStringProperty
and defaults to ‘out_back’.
- show_duration#
Duration of widget display transition.
show_duration
is aNumericProperty
and defaults to 0.2.
- hide_transition#
The type of transition of the widget closing.
hide_transition
is aStringProperty
and defaults to ‘out_cubic’.
- 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 aStringProperty
and defaults to ‘out_circ’.
- shift_transition#
Text label transition.
shift_transition
is aStringProperty
and defaults to ‘out_sine’.
- show_duration#
Duration of widget display transition.
show_duration
is aNumericProperty
and defaults to 0.3.
- hide_transition#
The type of transition of the widget closing.
hide_transition
is aStringProperty
and defaults to ‘linear’.
- hide_duration#
Duration of widget closing transition.
hide_duration
is aNumericProperty
and defaults to 0.2.
- 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 aStringProperty
and defaults to ‘out_expo’.
- show_button_container_transition#
The type of transition of the widget opening.
show_button_container_transition
is aStringProperty
and defaults to ‘out_circ’.
- hide_transition#
The type of transition of the widget opening.
show_transition
is aStringProperty
and defaults to ‘hide_transition’.
- show_duration#
Duration of widget display transition.
show_duration
is aNumericProperty
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()

API - kivymd.uix.behaviors.magic_behavior
#
- class kivymd.uix.behaviors.magic_behavior.MagicBehavior#
- magic_speed#
Animation playback speed.
magic_speed
is aNumericProperty
and defaults to 1.
- 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 anNumericProperty
and defaults to 0.
- rotate_value_axis#
Property for getting/setting the axis of the rotation.
rotate_value_axis
is anListProperty
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 anNumericProperty
and defaults to 1.
- scale_value_y#
Y-axis value.
scale_value_y
is anNumericProperty
and defaults to 1.
- scale_value_z#
Z-axis value.
scale_value_z
is anNumericProperty
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 anNumericProperty
and defaults to [].
ToggleButton#
API - kivymd.uix.behaviors.toggle_behavior
#
- class kivymd.uix.behaviors.toggle_behavior.MDToggleButtonBehavior(**kwargs)#
This mixin class provides
togglebutton
behavior. Please see thetogglebutton 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 aColorProperty
and is defaults to None.
- background_down#
Color of the button in
rgba
format for the ‘down’ state.background_down
is aColorProperty
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 aColorProperty
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 aColorProperty
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()

API - kivymd.uix.behaviors.hover_behavior
#
- class kivymd.uix.behaviors.hover_behavior.HoverBehavior(*args, **kwargs)#
- Events:
- 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 aBooleanProperty
and defaults to False.
- hover_visible#
True if hovering is True and is the current widget is visible.
hover_visible
is aBooleanProperty
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 aObjectProperty
and defaults to None.
- detect_visible#
Should this widget perform the visibility check?
detect_visible
is aBooleanProperty
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 aStringProperty
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 anVariableListProperty
and defaults to [0, 0, 0, 0].
- md_bg_color#
The background color of the widget (
Widget
) that will be inherited from theBackgroundColorBehavior
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 anColorProperty
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 anColorProperty
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 anNumericProperty
and defaults to 1.
- angle#
- background_origin#
- on_md_bg_color(instance, color: list | str)#
Fired when the values of
md_bg_color
change.
Elevation#
#
See also
Elevation is the relative distance between two surfaces along the z-axis.

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()
from kivy.uix.behaviors import ButtonBehavior
from kivymd.app import MDApp
from kivymd.uix.behaviors import (
RectangularRippleBehavior,
BackgroundColorBehavior,
CommonElevationBehavior,
)
from kivymd.uix.screen import MDScreen
class ElevationWidget(
RectangularRippleBehavior,
CommonElevationBehavior,
ButtonBehavior,
BackgroundColorBehavior,
):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.md_bg_color = "red"
self.size_hint = (None, None)
self.size = ("250dp", "50dp")
class Example(MDApp):
def build(self):
return (
MDScreen(
ElevationWidget(
pos_hint={"center_x": .5, "center_y": .6},
elevation=4,
shadow_softness=4,
shadow_offset=(0, -6),
),
ElevationWidget(
pos_hint={"center_x": .5, "center_y": .4},
),
)
)
Example().run()

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()
from kivy.metrics import dp
from kivy.uix.behaviors import ButtonBehavior
from kivymd.app import MDApp
from kivymd.uix.behaviors import CircularRippleBehavior, CommonElevationBehavior
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.label import MDIcon
from kivymd.uix.screen import MDScreen
class CircularElevationButton(
CommonElevationBehavior,
CircularRippleBehavior,
ButtonBehavior,
MDFloatLayout,
):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.size_hint = (None, None)
self.size = (dp(100), dp(100))
self.radius = dp(100) / 2
self.shadow_radius = dp(100) / 2
self.md_bg_color = "red"
self.add_widget(
MDIcon(
icon="hand-heart",
halign="center",
valign="center",
pos_hint={"center_x": .5, "center_y": .5},
size=self.size,
theme_text_color="Custom",
text_color="white",
font_size=self.size[0] * 0.6,
)
)
class Example(MDApp):
def build(self):
return (
MDScreen(
CircularElevationButton(
pos_hint={"center_x": .5, "center_y": .5},
elevation=4,
shadow_softness=4,
)
)
)
Example().run()

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()
from kivy.animation import Animation
from kivy.uix.behaviors import ButtonBehavior
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior, RectangularRippleBehavior
from kivymd.uix.screen import MDScreen
from kivymd.uix.widget import MDWidget
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 (
MDScreen(
ElevatedWidget(
pos_hint={'center_x': .5, 'center_y': .5},
size_hint=(None, None),
size=(100, 100),
md_bg_color="blue",
elevation=2,
radius=dp(18),
)
)
)
Example().run()

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 anBoundedNumericProperty
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 anDictProperty
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 anBoundedNumericProperty
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()
shadow_radius
is anVariableListProperty
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()
shadow_softness
is anNumericProperty
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()
ElevationWidget: shadow_offset: 12, -12
ElevationWidget: shadow_offset: 12, 12
ElevationWidget: shadow_offset: -12, 12
shadow_offset
is anListProperty
and defaults to (0, 0).
- shadow_color#
Offset of the shadow.
New in version 1.1.0.
ElevationWidget: shadow_color: 0, 0, 1, .8
shadow_color
is anColorProperty
and defaults to [0, 0, 0, 0.6].
- scale_value_x#
X-axis value.
New in version 1.2.0.
scale_value_x
is anNumericProperty
and defaults to 1.
- scale_value_y#
Y-axis value.
New in version 1.2.0.
scale_value_y
is anNumericProperty
and defaults to 1.
- scale_value_z#
Z-axis value.
New in version 1.2.0.
scale_value_z
is anNumericProperty
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 anNumericProperty
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 anNumericProperty
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 anListProperty
and defaults to (0, 0, 1).
State Layer#
#
See also
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
andButtonBehavior
classes documentation.- Events:
- state_layer_color#
The color of the layer state.
state_layer_color
is anColorProperty
and defaults to [0, 0, 0, 0].
- state_hover#
The transparency level of the layer as a percentage when hovering.
state_hover
is anNumericProperty
and defaults to 0.08.
- state_press#
The transparency level of the layer as a percentage when pressed.
state_press
is anNumericProperty
and defaults to 0.12.
- state_drag#
The transparency level of the layer as a percentage when dragged.
state_drag
is anNumericProperty
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#
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 anStringProperty
and defaults to ‘’.
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()

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

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
ripple_rad_default
is anNumericProperty
and defaults to 1.
- ripple_color#
Ripple color in (r, g, b, a) format.
CircularRippleButton: ripple_color: app.theme_cls.primary_color
ripple_color
is anColorProperty
and defaults to None.
- ripple_alpha#
Alpha channel values for ripple effect.
CircularRippleButton: ripple_alpha: .9 ripple_color: app.theme_cls.primary_color
ripple_alpha
is anNumericProperty
and defaults to 0.5.
- ripple_scale#
Ripple effect scale.
CircularRippleButton: ripple_scale: .5
CircularRippleButton: ripple_scale: 1
ripple_scale
is anNumericProperty
and defaults to None.
- ripple_duration_in_fast#
Ripple duration when touching to widget.
CircularRippleButton: ripple_duration_in_fast: .1
ripple_duration_in_fast
is anNumericProperty
and defaults to 0.3.
- ripple_duration_in_slow#
Ripple duration when long touching to widget.
CircularRippleButton: ripple_duration_in_slow: 5
ripple_duration_in_slow
is anNumericProperty
and defaults to 2.
- ripple_duration_out#
The duration of the disappearance of the wave effect.
CircularRippleButton: ripple_duration_out: 5
ripple_duration_out
is anNumericProperty
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"
MDIconButton: ripple_canvas_after: False icon: "android" ripple_alpha: .8 ripple_color: app.theme_cls.primary_color icon_size: "100sp"
ripple_canvas_after
is anBooleanProperty
and defaults to True.
- ripple_func_in#
Type of animation for ripple in effect.
ripple_func_in
is anStringProperty
and defaults to ‘out_quad’.
- ripple_func_out#
Type of animation for ripple out effect.
ripple_func_out
is anStringProperty
and defaults to ‘ripple_func_out’.
- ripple_effect#
Should I use the ripple effect.
ripple_effect
is anBooleanProperty
and defaults to True.
- abstract lay_canvas_instructions() NoReturn #
- on_touch_down(touch)#
- 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 anNumericProperty
and defaults to 2.75.
- 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 anNumericProperty
and defaults to 1.
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 anNumericProperty
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 anVariableListProperty
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()

Color change at focus/defocus
FocusWidget:
focus_color: 1, 0, 1, 1
unfocus_color: 0, 0, 1, 1

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
andButtonBehavior
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 aBooleanProperty
and defaults to False.
- focus_color#
The color of the widget when the mouse enters the bbox of the widget.
focus_color
is aColorProperty
and defaults to None.
- unfocus_color#
The color of the widget when the mouse exits the bbox widget.
unfocus_color
is aColorProperty
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 anNumericProperty
and defaults to ’20sp’.
- min#
Minimum boundary to stop the scrolling at.
min
is anNumericProperty
and defaults to 0.
- max#
Maximum boundary to stop the scrolling at.
max
is anNumericProperty
and defaults to 0.
- max_friction#
How hard should it be to scroll, at the worst?
max_friction
is anNumericProperty
and defaults to 1.
- body#
Proportion of the range in which you can scroll unimpeded.
body
is anNumericProperty
and defaults to 0.7.
- scroll#
Computed value for scrolling
scroll
is anNumericProperty
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 anObjectProperty
and defaults tokivy.animation.AnimationTransition
.
- transition_max#
The AnimationTransition function to use when adjusting the friction near the maximum end of the effect.
transition_max
is anObjectProperty
and defaults tokivy.animation.AnimationTransition
.
- target_widget#
The widget to apply the effect to.
target_widget
is anObjectProperty
and defaults toNone
.
- displacement#
The absolute distance moved in either direction.
displacement
is anNumericProperty
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
Bug fixes and other minor improvements.
[compare] Add supports Google’s Material Design 3 and the Material You concept.
[commit 25f242e] Add the feature to use icons from custom fonts.
[pull 1584] Implement bitmap scale down.
[commit 8ba6af9] Fix [issue 1593].
[commit b34b07f] Fix elevation properties.
[commit cb01c01] Fixed an infinite loop when typing text fast in the MDTextfield widget.
1.1.1#
See on GitHub: tag 1.1.1 | compare 1.0.2/1.1.1
pip install kivymd==1.1.1
Bug fixes and other minor improvements.
Add closing_interval parameter to MDCardSwipe class.
Add implementation of elevation behavior on shaders.
Add validator property to MDTextField class: 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.
Add theme_style_switch_animation property to animate the colors of the application when switching the color scheme of the application (‘Dark/light’).
Add theme_style_switch_animation_duration property to duration of the animation of switching the color scheme of the application (“Dark/ light”).
Fix memory leak when dynamically adding and removing KivyMD widgets.
Fix slide transition MDBottomNavigation direction.
Add new properties to MDFileManager class:
icon_selection_button - icon that will be used on the directory selection button;
background_color_selection_button - background color of the current directory/path selection button;
background_color_toolbar - background color of the file manager toolbar;
icon_color - color of the folder icon when the preview property is set to False;
Add binds to MDFloatingActionButtonSpeedDial individual buttons;
Add functionality for using multiple heroes.
Add shadow_softness_size attribute (value of the softness of the shadow) to CommonElevationBehavior class.
Optimize of MDDatePicker widget.
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
Bug fixes and other minor improvements.
1.0.0#
See on GitHub: tag 1.0.0 | compare 0.104.2/1.0.0
pip install kivymd==1.0.0
Bug fixes and other minor improvements.
Added ImageLeftWidgetWithoutTouch, ImageRightWidgetWithoutTouch, IconRightWidgetWithoutTouch, IconLeftWidgetWithoutTouch classes to kivymd/uix/list.py module;
Added MDStepper component;
Added a feature, show_disks to the MDFileManager class, that allows you to display the disks and folders contained in them;
Added animation_tooltip_dismiss function and on_dismiss event to MDTooltip class;
Added MDColorPicker component;
Added new transition package - a set of classes for implementing transitions between application screens;
Now all modules from the uix directory are packages;
Type hints have been added to the source code of the KivyMD library;
Added divider_color attribute to BaseListItem class;
Added load_all_kv_files method to MDApp class;
Added Templates package - base classes for controlling the scale, rotation of the widget, etc.;
Added kivymd/tools/patterns package - scripts for creating projects with design patterns;
FitImage widget move from kivymd.utils to kivymd.uix.fitimage;
Added background_color_header, background_color_cell, background_color_selected_cell, added methods for adding/removing rows to a common table to MDDataTable widget;
Added method for update rows to MDDataTable class;
Delete kivymd/utils/hot_reload_viewer.py;
Added kivymd/tools/hotreload package;
Added top value to position parameter of MDDropdownMenu class;
Added get_current_tab method to MDTabs class;
Added the feature to automatically create a virtual environment when creating a project using the kivymd.tools.patterns.create_project tool;
Added the feature to use the left_icon for MDTextField text fields;
The design and behavior of the MDChip widget is close to the material design spec;
Added the feature to set the thickness of the MDProgressBar class;
Added localization support when creating a project using the create_project tool;
Added support Material Design v3;
Added support badge icon to MDIcon class;
Added the feature to use a radius for the BaseListItem class;
MDFloatingActionButton class configured according to M3 style;
Ripple animation for round buttons customized to material design standards;
Fix Warning, too much iteration done before the next frame for button classes;
Added FadingEdgeEffect class
Added MDSliverAppBar widget;
Added the feature to use custom icons and font name for the MDBottomNavigation class;
Rename MDToolbar to MDTopAppBar class;
The overflow behavior from the ActionBar class of the Kivy framework has been added to the MDTopAppBar class;
Add shift_right and shift_right attributes to MDTooltip class;
Fixed the size of the MDIconButton icon when changing icon_size on mobile devices;
Add new MDSegmentedControl widget;
Add on_release/on_press events to MDSmartTile class;
Add mipmap property to FitImage class;
Added the feature to use Hero animation;
Added MDResponsiveLayout layout;
Added add_view utility;
Added the feature to create widgets in declarative programming style;
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 thekivy.uix.textinput.TextInput
class.Removed
kivymd.uix.textfield.MDTextFieldClear
class.kivymd.uix.navigationdrawer.NavigationLayout
allowed to addkivymd.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
orkivymd.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
Implemented the ability [Backdrop](https://material.io/components/backdrop)
Added MDApp class. Now app object should be inherited from kivymd.app.MDApp.
Added MDRoundImageButton class.
Added MDTooltip class.
Added MDBanner class.
Added hook for PyInstaller (add hookspath=[kivymd.hooks_path]).
Added examples of spec files for building [Kitchen Sink demo](https://github.com/kivymd/KivyMD/tree/master/demos/kitchen_sink).
Added some features to MDProgressLoader.
Added feature to preview the current value of MDSlider.
Added feature to use custom screens for dialog in MDBottomSheet class.
Removed MDPopupScreen.
Added [studies](https://github.com/kivymd/KivyMD/tree/master/demos/kitchen_sink/studies) directory for demos in Material Design.
Bug fixes and other minor improvements.
0.102.0#
See on GitHub: tag 0.102.0 | compare 0.101.8/0.102.0
pip install kivymd==0.102.0
Moved kivymd.behaviors to kivymd.uix.behaviors.
Updated [Iconic font](https://github.com/Templarian/MaterialDesign-Webfont) (v4.5.95).
Added blank icon to icon_definitions.
Bug fixes and other minor improvements.
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
Fixed colors and position of the buttons in the Buttons demo screen ([Kitchen Sink demo](https://github.com/kivymd/KivyMD/tree/master/demos/kitchen_sink)).
Displaying percent of loading kv-files ([Kitchen Sink demo](https://github.com/kivymd/KivyMD/tree/master/demos/kitchen_sink)).
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
Added feature to see source code of current example ([Kitchen Sink demo](https://github.com/kivymd/KivyMD/tree/master/demos/kitchen_sink)).
Added names of authors of this fork ([Kitchen Sink demo](https://github.com/kivymd/KivyMD/tree/master/demos/kitchen_sink)).
Bug fixes and other minor improvements.
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
Added MDContextMenu class.
Added MDExpansionPanel class.
Removed MDAccordion and MDAccordionListItem. Use MDExpansionPanel instead.
Added HoverBehavior class by [Olivier POYEN](https://gist.github.com/opqopq/15c707dc4cffc2b6455f).
Added markup support for buttons.
Added duration property to Toast.
Added TextInput’s events and properties to MDTextFieldRound.
Added feature to resize text field
Added color property to MDSeparator class
Added [tool](https://github.com/kivymd/KivyMD/blob/master/kivymd/tools/update_icons.py) for updating [Iconic font](https://github.com/Templarian/MaterialDesign-Webfont).
Updated [Iconic font](https://github.com/Templarian/MaterialDesign-Webfont) (v4.3.95).
Added new examples for [Kitchen Sink demo](https://github.com/kivymd/KivyMD/tree/master/demos/kitchen_sink).
Bug fixes and other minor improvements.
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
[Black](https://github.com/psf/black) formatting.
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
Added asynckivy module by [Nattōsai Mitō](https://github.com/gottadiveintopython/asynckivy).
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
Added function to create a round image in kivymd/utils/cropimage.py module.
Added MDCustomRoundIconButton class.
Added demo application [Account Page](https://www.youtube.com/watch?v=dfUOwqtYoYg) for [Kitchen Sink demo](https://github.com/kivymd/KivyMD/tree/master/demos/kitchen_sink).
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
Updated [Iconic font](https://github.com/Templarian/MaterialDesign-Webfont) (v3.6.95).
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#
#

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.

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. ReturnExceptionManager.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 aBooleanProperty
.
- FOREGROUND_LOCK#
If True it will require the foreground lock on windows.
FOREGROUND_LOCK
is aBooleanProperty
and defaults to False.
- KV_FILES#
List of KV files under management for auto reloader.
KV_FILES
is aListProperty
and defaults to [].
- KV_DIRS#
List of managed KV directories for autoloader.
KV_DIRS
is aListProperty
and defaults to [].
- AUTORELOADER_PATHS#
List of path to watch for auto reloading.
AUTORELOADER_PATHS
is aListProperty
and defaults to ([(“.”, {“recursive”: True})].
- AUTORELOADER_IGNORE_PATTERNS#
List of extensions to ignore.
AUTORELOADER_IGNORE_PATTERNS
is aListProperty
and defaults to [‘*.pyc’, ‘*__pycache__*’].
- CLASSES#
Factory classes managed by hotreload.
CLASSES
is aDictProperty
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 aBooleanProperty
and defaults to False.
- IDLE_TIMEOUT#
Default idle timeout.
IDLE_TIMEOUT
is aNumericProperty
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 aBooleanProperty
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.
See also
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
Use a clean architecture for your applications.

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.

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.

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.
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.
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
#
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.git_clean(ask: bool = True)#
Clean git repository from untracked and changed files.
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.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 anBooleanProperty
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 anBooleanProperty
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 anBooleanProperty
and defaults to False.
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.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.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.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 anNumericProperty
and defaults to 0.5.
- anchor#
Monitor position. Available option are: ‘top’, ‘bottom’.
anchor
is anOptionProperty
and defaults to ‘top’.
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.
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()
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 )
New in version 1.0.0.