Theming

See also

Material Design spec, Material 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": {
        "50": "e4f8f9",
        "100": "bdedf0",
        "200": "97e2e8",
        "300": "79d5de",
        "400": "6dcbd6",
        "500": "6ac2cf",
        "600": "63b2bc",
        "700": "5b9ca3",
        "800": "54888c",
        "900": "486363",
        "A100": "bdedf0",
        "A200": "97e2e8",
        "A400": "6dcbd6",
        "A700": "5b9ca3",
    },
    "Blue": {
        "50": "e3f3f8",
        "100": "b9e1ee",
        "200": "91cee3",
        "300": "72bad6",
        "400": "62acce",
        "500": "589fc6",
        "600": "5191b8",
        "700": "487fa5",
        "800": "426f91",
        "900": "35506d",
        "A100": "b9e1ee",
        "A200": "91cee3",
        "A400": "62acce",
        "A700": "487fa5",
    },
    "Light": {
        "StatusBar": "E0E0E0",
        "AppBar": "F5F5F5",
        "Background": "FAFAFA",
        "CardsDialogs": "FFFFFF",
        "FlatButtonDown": "cccccc",
    },
    "Dark": {
        "StatusBar": "000000",
        "AppBar": "212121",
        "Background": "303030",
        "CardsDialogs": "424242",
        "FlatButtonDown": "999999",
    }
}


KV = '''
BoxLayout:
    orientation: "vertical"
    MDToolbar:
        title: "Example Tabs"
    MDTabs:
        id: tabs


<Tab>

    MDIconButton:
        id: icon
        icon: root.icon
        user_font_size: "48sp"
        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 = "Blue"
        self.theme_cls.accent_palette = "Teal"
        return Builder.load_string(KV)

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


Example().run()

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

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.uix.screenmanager import Screen

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


class MainApp(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Green"  # "Purple", "Red"

        screen = Screen()
        screen.add_widget(
            MDRectangleFlatButton(
                text="Hello, World",
                pos_hint={"center_x": 0.5, "center_y": 0.5},
            )
        )
        return screen


MainApp().run()

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 kivy.uix.screenmanager import Screen

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


class MainApp(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Green"  # "Purple", "Red"
        self.theme_cls.primary_hue = "200"  # "500"

        screen = Screen()
        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 = "500":

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

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 in rgba format.

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 rgba format (in lighter color).

from kivy.lang import Builder

from kivymd.app import MDApp


KV = '''
Screen:

    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 = "Green"
        return Builder.load_string(KV)


MainApp().run()

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 rgba format (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…

The image below shows the color schemes with the values self.theme_cls.accent_palette = 'Blue', Red' and​​ Yellow':

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.

theme_style

App theme style.

from kivy.uix.screenmanager import Screen

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


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

        screen = Screen()
        screen.add_widget(
            MDRectangleFlatButton(
                text="Hello, World",
                pos_hint={"center_x": 0.5, "center_y": 0.5},
            )
        )
        return screen


MainApp().run()

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.

KV = '''
<Box@BoxLayout>:
    bg: 0, 0, 0, 0

    canvas:
        Color:
            rgba: root.bg
        Rectangle:
            pos: self.pos
            size: self.size

BoxLayout:

    Box:
        bg: app.theme_cls.bg_light
    Box:
        bg: app.theme_cls.bg_normal
    Box:
        bg: app.theme_cls.bg_dark
    Box:
        bg: app.theme_cls.bg_darkest
'''

from kivy.lang import Builder

from kivymd.app import MDApp


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


MainApp().run()

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.

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.

set_clearcolor

font_styles

Data of default font styles.

Add custom font:

KV = '''
Screen:

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

from kivy.core.text import LabelBase

from kivy.lang import Builder

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


class MainApp(MDApp):
    def build(self):
        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()

font_styles is an DictProperty.

on_theme_style(self, instance, value)

set_clearcolor_by_theme_style(self, theme_style)

set_colors(self, primary_palette, primary_hue, primary_light_hue, primary_dark_hue, accent_palette, accent_hue, accent_light_hue, accent_dark_hue)

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 kivy.uix.screenmanager import Screen

from kivymd.app import MDApp
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 = Screen()
        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"

widget_style is an OptionProperty and defaults to ‘android’.

opposite_colors