Theming

See also

Material Design spec, Dynamic color

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.

Added 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.

Works like a ColorProperty, but also accepts color names from kivy.utils.hex_colormap, including keys with capital letters.

To change the color scheme of an application:

Imperative python style with KVDeclarative python style

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

primary_palette is an OptionProperty and defaults to None.

dynamic_color_quality

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

Warning

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

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

dynamic_color

Enables or disables dynamic color.

Added in version 2.0.0.

See also

Material Design spec, Dynamic color

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:

Imperative python style with KVDeclarative python style

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)

        if platform == "android":
            from android.permissions import Permission, request_permissions

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


Example().run()

dynamic_color is an BooleanProperty and defaults to False.

dynamic_scheme_name

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

dynamic_scheme_name is an OptionProperty and defaults to ‘TONAL_SPOT’.

dynamic_scheme_contrast

The contrast of the generated color scheme.

dynamic_scheme_contrast is an NumericProperty and defaults to 0.0.

path_to_wallpaper

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

Added in version 2.0.0.

path_to_wallpaper is an StringProperty and defaults to ‘’.

theme_style_switch_animation

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

Added in version 1.1.0.

Declarative KV styleDeclarative python style

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

theme_style_switch_animation is an BooleanProperty and defaults to True.

theme_style_switch_animation_duration

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

Added 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 an NumericProperty and defaults to 0.2.

theme_style

App theme style.

from kivy.clock import Clock

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


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

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

        Clock.schedule_once(on_start)


Example().run()

theme_style is an OptionProperty and defaults to ‘Light’.

disabled_hint_text_color

Color of the disabled text used in the MDTextField.

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

device_orientation

Device orientation.

device_orientation is an StringProperty and defaults to ‘’.

font_styles

Data of default font styles.

Add custom font

Declarative style with KVDeclarative python style

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

font_styles is an DictProperty.

on_colors

A Helper function called when colors are changed.

Attr:

on_colors defaults to None.

dynamic_color_names

List of material design dynamic color palette names:

• backgroundColor

• disabledTextColor

• errorColor

• errorContainerColor

• inverseOnSurfaceColor

• inversePrimaryColor

• inverseSurfaceColor

• neutral_paletteKeyColorColor

• neutral_variant_paletteKeyColorColor

• onBackgroundColor

• onErrorColor

• onErrorContainerColor

• onPrimaryColor

• onPrimaryContainerColor

• onPrimaryFixedColor

• onPrimaryFixedVariantColor

• onSecondaryColor

• onSecondaryContainerColor

• onSecondaryFixedColor

• onSecondaryFixedVariantColor

• onSurfaceColor

• onSurfaceLightColor

• onSurfaceVariantColor

• onTertiaryColor

• onTertiaryContainerColor

• onTertiaryFixedColor

• onTertiaryFixedVariantColor

• outlineColor

• outlineVariantColor

• primaryColor

• primaryContainerColor

• primaryFixedColor

• primaryFixedDimColor

• primary_paletteKeyColorColor

• rippleColor

• scrimColor

• secondaryColor

• secondaryContainerColor

• secondaryFixedColor

• secondaryFixedDimColor

• secondary_paletteKeyColorColor

• shadowColor

• surfaceBrightColor

• surfaceColor

• surfaceContainerColor

• surfaceContainerHighColor

• surfaceContainerHighestColor

• surfaceContainerLowColor

• surfaceContainerLowestColor

• surfaceDimColor

• surfaceTintColor

• surfaceVariantColor

• tertiaryColor

• tertiaryContainerColor

• tertiaryFixedColor

• tertiaryFixedDimColor

• tertiary_paletteKeyColorColor

• transparentColor

dynamic_color_names is an AliasProperty and for internal usage only.

set_colors(*args) → None

Fired methods for setting a new color scheme.

update_theme_colors(*args) → None

Fired when the theme_style value changes.

on_dynamic_scheme_name(*args) → None

Fired when the dynamic_scheme_name value changes.

on_dynamic_scheme_contrast(*args) → None

Fired when the dynamic_scheme_contrast value changes.

on_path_to_wallpaper(*args) → None

Fired when the path_to_wallpaper value changes.

switch_theme() → None

Switches the theme from light to dark.

sync_theme_styles(*args) → None

color_to_rgba(color)

class kivymd.theming.ThemableBehavior(**kwargs)

theme_cls

Instance of ThemeManager class.

theme_cls is an ObjectProperty.

device_ios

True if device is iOS.

device_ios is an BooleanProperty.

theme_line_color

Line color scheme name.

Added in version 2.0.0.

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

theme_line_color is an OptionProperty and defaults to ‘Primary’.

theme_bg_color

Background color scheme name.

Added in version 2.0.0.

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

theme_bg_color is an OptionProperty and defaults to ‘Primary’.

theme_shadow_color

Elevation color scheme name.

Added in version 2.0.0.

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

theme_shadow_color is an OptionProperty and defaults to ‘Primary’.

theme_shadow_offset

Elevation offset scheme name.

Added in version 2.0.0.

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

theme_shadow_offset is an OptionProperty and defaults to ‘Primary’.

theme_elevation_level

Elevation level scheme name.

Added in version 2.0.0.

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

theme_elevation_level is an OptionProperty and defaults to ‘Primary’.

theme_font_size

Font size scheme name.

Added in version 2.0.0.

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

theme_font_size is an OptionProperty and defaults to ‘Primary’.

theme_width

Widget width scheme name.

Added in version 2.0.0.

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

theme_width is an OptionProperty and defaults to ‘Primary’.

theme_height

Widget width scheme name.

Added in version 2.0.0.

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

theme_height is an OptionProperty and defaults to ‘Primary’.

theme_line_height

Line height scheme name.

Added in version 2.0.0.

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

theme_line_height is an OptionProperty and defaults to ‘Primary’.

theme_font_name

Font name scheme name.

Added in version 2.0.0.

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

theme_font_name is an OptionProperty and defaults to ‘Primary’.

theme_shadow_softness

Elevation softness scheme name.

Added in version 2.0.0.

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

theme_shadow_softness is an OptionProperty and defaults to ‘Primary’.

theme_focus_color

Focus color scheme name.

Added in version 2.0.0.

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

theme_focus_color is an OptionProperty and defaults to ‘Primary’.

theme_divider_color

Divider color scheme name.

Added in version 2.0.0.

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

theme_divider_color is an OptionProperty and defaults to ‘Primary’.

theme_text_color

Label color scheme name.

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

theme_text_color is an OptionProperty and defaults to ‘Primary’.

theme_icon_color

Label color scheme name.

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

theme_icon_color is an OptionProperty and defaults to ‘Primary’.

remove_widget(widget) → None