Theming#

Material App#

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

Control material properties#

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

Changing the theme colors#

The standard theme_cls is designed to provide the standard themes and colors as defined by Material Design.

We do not recommend that you change this.

However, if you do need to change the standard colors, for instance to meet branding guidelines, you can do this by overloading the color_definitions.py object.

Create a custom color defintion object. This should have the same format as the colors object in color_definitions.py and contain definitions for at least the primary color, the accent color and the Light and Dark backgrounds.

Note

Your custom colors must use the names of the existing colors as defined in the palette e.g. You can have Blue but you cannot have NavyBlue.

Add the custom theme to the MDApp as shown in the following snippet.

from kivy.lang import Builder
from kivy.properties import ObjectProperty

from kivymd.app import MDApp
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.tab import MDTabsBase
from kivymd.icon_definitions import md_icons

colors = {
    "Teal": {
        "200": "#212121",
        "500": "#212121",
        "700": "#212121",
    },
    "Red": {
        "200": "#C25554",
        "500": "#C25554",
        "700": "#C25554",
    },
    "Light": {
        "StatusBar": "E0E0E0",
        "AppBar": "#202020",
        "Background": "#2E3032",
        "CardsDialogs": "#FFFFFF",
        "FlatButtonDown": "#CCCCCC",
    },
}


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

    MDTopAppBar:
        title: "Custom theme"

    MDTabs:
        id: tabs


<Tab>

    MDIconButton:
        id: icon
        icon: root.icon
        icon_size: "48sp"
        theme_icon_color: "Custom"
        icon_color: "white"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Tab(MDFloatLayout, MDTabsBase):
    '''Class implementing content for a tab.'''

    icon = ObjectProperty()


class Example(MDApp):
    icons = list(md_icons.keys())[15:30]

    def build(self):
        self.theme_cls.colors = colors
        self.theme_cls.primary_palette = "Teal"
        self.theme_cls.accent_palette = "Red"
        return Builder.load_string(KV)

    def on_start(self):
        for name_tab in self.icons:
            tab = Tab(title="This is " + name_tab, icon=name_tab)
            self.root.ids.tabs.add_widget(tab)


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

This will change the theme colors to your custom definition. In all other respects, the theming stays as documented.

Warning

Please note that the key 'Red' is a required key for the dictionary kivymd.color_definition.colors.

API - kivymd.theming#

class kivymd.theming.ThemeManager(**kwargs)#
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.

Available options are: ‘Red’, ‘Pink’, ‘Purple’, ‘DeepPurple’, ‘Indigo’, ‘Blue’, ‘LightBlue’, ‘Cyan’, ‘Teal’, ‘Green’, ‘LightGreen’, ‘Lime’, ‘Yellow’, ‘Amber’, ‘Orange’, ‘DeepOrange’, ‘Brown’, ‘Gray’, ‘BlueGray’.

To change the color scheme of an application:

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDRectangleFlatButton:
        text: "Hello, World"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


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

        return Builder.load_string(KV)


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

primary_palette is an OptionProperty and defaults to ‘Blue’.

primary_hue#

The color hue of the application.

Available options are: ‘50’, ‘100’, ‘200’, ‘300’, ‘400’, ‘500’, ‘600’, ‘700’, ‘800’, ‘900’, ‘A100’, ‘A200’, ‘A400’, ‘A700’.

To change the hue color scheme of an application:

from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen
from kivymd.uix.button import MDRectangleFlatButton


class MainApp(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.primary_hue = "200"  # "500"
        screen = MDScreen()
        screen.add_widget(
            MDRectangleFlatButton(
                text="Hello, World",
                pos_hint={"center_x": 0.5, "center_y": 0.5},
            )
        )
        return screen


MainApp().run()

With a value of self.theme_cls.primary_hue = "200" and self.theme_cls.primary_hue = "500":

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

primary_hue is an OptionProperty and defaults to ‘500’.

primary_light_hue#

Hue value for primary_light.

primary_light_hue is an OptionProperty and defaults to ‘200’.

primary_dark_hue#

Hue value for primary_dark.

primary_light_hue is an OptionProperty and defaults to ‘700’.

primary_color#

The color of the current application theme.

primary_color is an AliasProperty that returns the value of the current application theme, property is readonly.

primary_light#

Colors of the current application color theme (in lighter color).

from kivy.lang import Builder

from kivymd.app import MDApp


KV = '''
MDScreen:

    MDRaisedButton:
        text: "primary_light"
        pos_hint: {"center_x": 0.5, "center_y": 0.7}
        md_bg_color: app.theme_cls.primary_light

    MDRaisedButton:
        text: "primary_color"
        pos_hint: {"center_x": 0.5, "center_y": 0.5}

    MDRaisedButton:
        text: "primary_dark"
        pos_hint: {"center_x": 0.5, "center_y": 0.3}
        md_bg_color: app.theme_cls.primary_dark
'''


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


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

primary_light is an AliasProperty that returns the value of the current application theme (in lighter color), property is readonly.

primary_dark#

Colors of the current application color theme (in darker color).

primary_dark is an AliasProperty that returns the value of the current application theme (in darker color), property is readonly.

accent_palette#

The application color palette used for items such as the tab indicator in the MDTabsBar class and so on. See kivymd.uix.tab.MDTabsBar.indicator_color attribute.

accent_palette is an OptionProperty and defaults to ‘Amber’.

accent_hue#

Similar to primary_hue, but returns a value for accent_palette.

accent_hue is an OptionProperty and defaults to ‘500’.

accent_light_hue#

Hue value for accent_light.

accent_light_hue is an OptionProperty and defaults to ‘200’.

accent_dark_hue#

Hue value for accent_dark.

accent_dark_hue is an OptionProperty and defaults to ‘700’.

accent_color#

Similar to primary_color, but returns a value for accent_color.

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

accent_light#

Similar to primary_light, but returns a value for accent_light.

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

accent_dark#

Similar to primary_dark, but returns a value for accent_dark.

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

material_style#

Material design style. Available options are: ‘M2’, ‘M3’.

New in version 1.0.0.

material_style is an OptionProperty and defaults to ‘M2’.

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:

    MDCard:
        orientation: "vertical"
        padding: 0, 0, 0 , "36dp"
        size_hint: .5, .5
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 4
        shadow_radius: 6
        shadow_offset: 0, 2

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

        MDRaisedButton:
            text: "Set theme"
            on_release: app.switch_theme_style()
            pos_hint: {"center_x": .5}
'''


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

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


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

theme_style_switch_animation is an BooleanProperty and defaults to False.

theme_style_switch_animation_duration#

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

New in version 1.1.0.

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

theme_style_switch_animation_duration is an NumericProperty and defaults to 0.2.

theme_style#

App theme style.

from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen
from kivymd.uix.button import MDRectangleFlatButton


class MainApp(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Orange"
        self.theme_cls.theme_style = "Dark"  # "Light"
        screen = MDScreen()
        screen.add_widget(
            MDRectangleFlatButton(
                text="Hello, World",
                pos_hint={"center_x": 0.5, "center_y": 0.5},
            )
        )
        return screen


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

theme_style is an OptionProperty and defaults to ‘Light’.

bg_darkest#

Similar to bg_dark, but the color values are a tone lower (darker) than bg_dark.

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDBoxLayout:

    MDWidget:
        md_bg_color: app.theme_cls.bg_light

    MDBoxLayout:
        md_bg_color: app.theme_cls.bg_normal

    MDBoxLayout:
        md_bg_color: app.theme_cls.bg_dark

    MDBoxLayout:
        md_bg_color: app.theme_cls.bg_darkest
'''


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


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

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

opposite_bg_darkest#

The opposite value of color in the bg_darkest.

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

bg_dark#

Similar to bg_normal, but the color values are one tone lower (darker) than bg_normal.

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

opposite_bg_dark#

The opposite value of color in the bg_dark.

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

bg_normal#

Similar to bg_light, but the color values are one tone lower (darker) than bg_light.

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

opposite_bg_normal#

The opposite value of color in the bg_normal.

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

bg_light#

” Depending on the style of the theme (‘Dark’ or ‘Light’) that the application uses, bg_light contains the color value in rgba format for the widgets background.

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

opposite_bg_light#

The opposite value of color in the bg_light.

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

divider_color#

Color for dividing lines such as MDSeparator.

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

opposite_divider_color#

The opposite value of color in the divider_color.

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

disabled_primary_color#

The greyscale disabled version of the current application theme color in rgba format.

New in version 1.0.0.

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

opposite_disabled_primary_color#

The opposite value of color in the disabled_primary_color.

New in version 1.0.0.

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

text_color#

Color of the text used in the MDLabel.

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

opposite_text_color#

The opposite value of color in the text_color.

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

secondary_text_color#

The color for the secondary text that is used in classes from the module TwoLineListItem.

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

opposite_secondary_text_color#

The opposite value of color in the secondary_text_color.

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

icon_color#

Color of the icon used in the MDIconButton.

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

opposite_icon_color#

The opposite value of color in the icon_color.

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

disabled_hint_text_color#

Color of the disabled text used in the MDTextField.

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

opposite_disabled_hint_text_color#

The opposite value of color in the disabled_hint_text_color.

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

error_color#

Color of the error text used in the MDTextField.

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

ripple_color#

Color of ripple effects.

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

device_orientation#

Device orientation.

device_orientation is an StringProperty.

standard_increment#

Value of standard increment.

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

horizontal_margins#

Value of horizontal margins.

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

font_styles#

Data of default font styles.

from kivy.core.text import LabelBase
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.font_definitions import theme_font_styles

KV = '''
MDScreen:

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


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

        LabelBase.register(
            name="JetBrainsMono",
            fn_regular="JetBrainsMono-Regular.ttf")

        theme_font_styles.append('JetBrainsMono')
        self.theme_cls.font_styles["JetBrainsMono"] = [
            "JetBrainsMono",
            16,
            False,
            0.15,
        ]
        return Builder.load_string(KV)


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

font_styles is an DictProperty.

on_theme_style(self, interval: int, theme_style: str)#
set_clearcolor_by_theme_style(self, theme_style)#
set_colors(self, primary_palette: str, primary_hue: str, primary_light_hue: str, primary_dark_hue: str, accent_palette: str, accent_hue: str, accent_light_hue: str, accent_dark_hue: str)#

Courtesy method to allow all of the theme color attributes to be set in one call.

set_colors allows all of the following to be set in one method call:

  • primary palette color,

  • primary hue,

  • primary light hue,

  • primary dark hue,

  • accent palette color,

  • accent hue,

  • accent ligth hue, and

  • accent dark hue.

Note that all values must be provided. If you only want to set one or two values use the appropriate method call for that.

from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen
from kivymd.uix.button import MDRectangleFlatButton

class MainApp(MDApp):
    def build(self):
        self.theme_cls.set_colors(
            "Blue", "600", "50", "800", "Teal", "600", "100", "800"
        )
        screen = MDScreen()
        screen.add_widget(
            MDRectangleFlatButton(
                text="Hello, World",
                pos_hint={"center_x": 0.5, "center_y": 0.5},
            )
        )
        return screen


MainApp().run()
sync_theme_styles(self, *args)#
class kivymd.theming.ThemableBehavior(**kwargs)#
theme_cls#

Instance of ThemeManager class.

theme_cls is an ObjectProperty.

device_ios#

True if device is iOS.

device_ios is an BooleanProperty.

widget_style#

Allows to set one of the three style properties for the widget: ‘android’, ‘ios’, ‘desktop’.

For example, for the class MDSwitch has two styles - ‘android’ and ‘ios’:

MDSwitch:
    widget_style: "ios"
MDSwitch:
    widget_style: "android"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-android-ios.png

widget_style is an OptionProperty and defaults to ‘android’.

opposite_colors#

For some widgets, for example, for a widget MDTopAppBar changes the color of the label to the color opposite to the main theme.

MDTopAppBar:
    title: "MDTopAppBar"
    opposite_colors: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-opposite-true.png
MDTopAppBar:
    title: "MDTopAppBar"
    opposite_colors: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/toolbar-opposite-false.png
dec_disabled(self, *args, **kwargs)#