Theming#

#

Material App#

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

Control material properties#

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

API - kivymd.theming#

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

Dynamic color class.

New in version 2.0.0.

primary_palette#

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

See kivy.utils.hex_colormap keys for available values.

To change the color scheme of an application:

from kivy.lang import Builder

from kivymd.app import MDApp

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

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

        MDButtonIcon:
            icon: "plus"

        MDButtonText:
            text: "Button"
'''


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


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

primary_palette is an OptionProperty and defaults to None.

dynamic_color_quality#

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

Warning

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

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

dynamic_color#

Enables or disables dynamic color.

New in version 2.0.0.

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

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

from kivymd.app import MDApp

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

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

        MDButtonIcon:
            icon: "plus"

        MDButtonText:
            text: "Elevated"
'''


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

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

        self.theme_cls.set_colors()

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

        self.theme_cls.dynamic_color = True

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

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

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

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


Example().run()

dynamic_color is an BooleanProperty and defaults to False.

dynamic_scheme_name#

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

dynamic_scheme_name is an OptionProperty and defaults to ‘TONAL_SPOT’.

dynamic_scheme_contrast#

The contrast of the generated color scheme.

dynamic_scheme_contrast is an NumericProperty and defaults to 0.0.

path_to_wallpaper#

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

New in version 2.0.0.

path_to_wallpaper is an StringProperty and defaults to ‘’.

theme_style_switch_animation#

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

New in version 1.1.0.

from kivy.lang import Builder

from kivymd.app import MDApp

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

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

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

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

            MDButtonText:
                text: "Set theme"
'''


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

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


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

theme_style_switch_animation is an BooleanProperty and defaults to True.

theme_style_switch_animation_duration#

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

New in version 1.1.0.

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

theme_style_switch_animation_duration is an NumericProperty and defaults to 0.2.

theme_style#

App theme style.

from kivy.clock import Clock

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


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

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

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


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

theme_style is an OptionProperty and defaults to ‘Light’.

disabled_hint_text_color#

Color of the disabled text used in the MDTextField.

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

device_orientation#

Device orientation.

device_orientation is an StringProperty and defaults to ‘’.

font_styles#

Data of default font styles.

Add custom font#

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

from kivymd.app import MDApp

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

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


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

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

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

        return Builder.load_string(KV)


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

font_styles is an DictProperty.

on_colors#

A Helper function called when colors are changed.

Attr:

on_colors defaults to None.

set_colors(*args) None#

Fired methods for setting a new color scheme.

update_theme_colors(*args) None#

Fired when the theme_style value changes.

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

Switches the theme from light to dark.

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

Instance of ThemeManager class.

theme_cls is an ObjectProperty.

device_ios#

True if device is iOS.

device_ios is an BooleanProperty.

theme_line_color#

Line color scheme name.

New in version 2.0.0.

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

theme_line_color is an OptionProperty and defaults to ‘Primary’.

theme_bg_color#

Background color scheme name.

New in version 2.0.0.

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

theme_bg_color is an OptionProperty and defaults to ‘Primary’.

theme_shadow_color#

Elevation color scheme name.

New in version 2.0.0.

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

theme_shadow_color is an OptionProperty and defaults to ‘Primary’.

theme_shadow_offset#

Elevation offset scheme name.

New in version 2.0.0.

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

theme_shadow_offset is an OptionProperty and defaults to ‘Primary’.

theme_elevation_level#

Elevation level scheme name.

New in version 2.0.0.

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

theme_elevation_level is an OptionProperty and defaults to ‘Primary’.

theme_font_size#

Font size scheme name.

New in version 2.0.0.

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

theme_font_size is an OptionProperty and defaults to ‘Primary’.

theme_width#

Widget width scheme name.

New in version 2.0.0.

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

theme_width is an OptionProperty and defaults to ‘Primary’.

theme_height#

Widget width scheme name.

New in version 2.0.0.

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

theme_height is an OptionProperty and defaults to ‘Primary’.

theme_line_height#

Line height scheme name.

New in version 2.0.0.

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

theme_line_height is an OptionProperty and defaults to ‘Primary’.

theme_font_name#

Font name scheme name.

New in version 2.0.0.

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

theme_font_name is an OptionProperty and defaults to ‘Primary’.

theme_shadow_softness#

Elevation softness scheme name.

New in version 2.0.0.

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

theme_shadow_softness is an OptionProperty and defaults to ‘Primary’.

theme_focus_color#

Focus color scheme name.

New in version 2.0.0.

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

theme_focus_color is an OptionProperty and defaults to ‘Primary’.

theme_divider_color#

Divider color scheme name.

New in version 2.0.0.

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

theme_divider_color is an OptionProperty and defaults to ‘Primary’.

theme_text_color#

Label color scheme name.

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

theme_text_color is an OptionProperty and defaults to ‘Primary’.

theme_icon_color#

Label color scheme name.

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

theme_icon_color is an OptionProperty and defaults to ‘Primary’.

remove_widget(widget) None#