Label

The MDLabel widget is for rendering text.

• MDLabel

• MDIcon

MDLabel

Class MDLabel inherited from the Label class but for MDLabel the text_size parameter is (self.width, None) and default is positioned on the left:

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDLabel:
        text: "MDLabel"
'''


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


Test().run()

Note

See halign and valign attributes of the Label class

MDLabel:
    text: "MDLabel"
    halign: "center"

MDLabel color:

MDLabel provides standard color themes for label color management:

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.label import MDLabel

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


class Test(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        screen = Builder.load_string(KV)

        # Names of standard color themes.
        for name_theme in [
            "Primary",
            "Secondary",
            "Hint",
            "Error",
            "ContrastParentBackground",
        ]:
            screen.add_widget(
                MDLabel(
                    text=name_theme,
                    halign="center",
                    theme_text_color=name_theme,
                )
            )
        return screen


Test().run()

To use a custom color for MDLabel, use a theme ‘Custom’. After that, you can specify the desired color in the rgba format in the text_color parameter:

MDLabel:
    text: "Custom color"
    halign: "center"
    theme_text_color: "Custom"
    text_color: "blue"

MDLabel provides standard font styles for labels. To do this, specify the name of the desired style in the font_style parameter:

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.font_definitions import theme_font_styles

KV = '''
MDScrollView:

    MDList:
        id: box
        spacing: "8dp"
'''


class Test(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        screen = Builder.load_string(KV)

        # Names of standard font styles.
        for name_style in theme_font_styles[:-1]:
            screen.ids.box.add_widget(
                MDLabel(
                    text=f"{name_style} style",
                    halign="center",
                    font_style=name_style,
                    adaptive_height=True,
                )
            )
        return screen


Test().run()

Highlighting and copying labels

You can highlight labels by double tap on the label:

Declarative KV styleDeclarative Python style

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"
        allow_selection: True
        padding: "4dp", "4dp"
'''


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

You can copy the label text by double clicking on it:

Declarative KV styleDeclarative Python style

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

Example of copying/cutting labels using the context menu

from kivy.core.clipboard import Clipboard
from kivy.lang.builder import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.uix.menu import MDDropdownMenu
from kivymd.toast import toast

KV = '''
MDBoxLayout:
    orientation: "vertical"
    spacing: "12dp"
    padding: "24dp"

    MDScrollView:

        MDBoxLayout:
            id: box
            orientation: "vertical"
            padding: "24dp"
            spacing: "12dp"
            adaptive_height: True

    MDTextField:
        max_height: "200dp"
        mode: "fill"
        multiline: True

    MDWidget:
'''

data = [
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "Sed blandit libero volutpat sed cras ornare arcu. Nisl vel pretium "
    "lectus quam id leo in. Tincidunt arcu non sodales neque sodales ut etiam.",
    "Elit scelerisque mauris pellentesque pulvinar pellentesque habitant. "
    "Nisl rhoncus mattis rhoncus urna neque. Orci nulla pellentesque "
    "dignissim enim. Ac auctor augue mauris augue neque gravida in fermentum. "
    "Lacus suspendisse faucibus interdum posuere."

]


class CopyLabel(MDLabel):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.allow_selection = True
        self.adaptive_height = True
        self.theme_text_color = "Custom"
        self.text_color = self.theme_cls.text_color


class Example(MDApp):
    context_menu = None

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

    def on_start(self):
        for text in data:
            copy_label = CopyLabel(text=text)
            copy_label.bind(
                on_selection=self.open_context_menu,
                on_cancel_selection=self.restore_text_color,
            )
            self.root.ids.box.add_widget(copy_label)

    def click_item_context_menu(
        self, type_click: str, instance_label: CopyLabel
    ) -> None:
        Clipboard.copy(instance_label.text)

        if type_click == "copy":
            toast("Copied")
        elif type_click == "cut":
            self.root.ids.box.remove_widget(instance_label)
            toast("Cut")
        if self.context_menu:
            self.context_menu.dismiss()

    def restore_text_color(self, instance_label: CopyLabel) -> None:
        instance_label.text_color = self.theme_cls.text_color

    def open_context_menu(self, instance_label: CopyLabel) -> None:
        instance_label.text_color = "black"
        menu_items = [
            {
                "text": "Copy text",
                "viewclass": "OneLineListItem",
                "height": dp(48),
                "on_release": lambda: self.click_item_context_menu(
                    "copy", instance_label
                ),
            },
            {
                "text": "Cut text",
                "viewclass": "OneLineListItem",
                "height": dp(48),
                "on_release": lambda: self.click_item_context_menu(
                    "cut", instance_label
                ),
            },
        ]
        self.context_menu = MDDropdownMenu(
            caller=instance_label, items=menu_items, width_mult=3
        )
        self.context_menu.open()


Example().run()

MDIcon

You can use labels to display material design icons using the MDIcon class.

See also

Material Design Icons

Material Design Icon Names

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"
    pos_hint: {"center_x": .5, "center_y": .5}

MDIcon with badge icon

MDIcon:
    icon: "gmail"
    badge_icon: "numeric-10"
    pos_hint: {"center_x": .5, "center_y": .5}

API - kivymd.uix.label.label

class kivymd.uix.label.label.MDLabel(*args, **kwargs)

Label class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and Label and MDAdaptiveWidget and TouchBehavior classes documentation.

Events:

on_ref_press

Called when the user clicks on a word referenced with a [ref] tag in a text markup.

on_copy

Called when double-tapping on the label.

on_selection

Called when double-tapping on the label.

on_cancel_selection

Called when the highlighting is removed from the label text.

font_style

Label font style.

Available vanilla font_style are: ‘H1’, ‘H2’, ‘H3’, ‘H4’, ‘H5’, ‘H6’, ‘Subtitle1’, ‘Subtitle2’, ‘Body1’, ‘Body2’, ‘Button’, ‘Caption’, ‘Overline’, ‘Icon’.

font_style is an StringProperty and defaults to ‘Body1’.

text

Text of the label.

theme_text_color

Label color scheme name.

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

theme_text_color is an OptionProperty and defaults to None.

text_color

Label text color in (r, g, b, a) or string format.

text_color is an ColorProperty 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 an BooleanProperty 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 an BooleanProperty 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 an ColorProperty 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 an ColorProperty and defaults to None.

is_selected

Is the label text highlighted.

New in version 1.2.0.

is_selected is an BooleanProperty and defaults to False.

parent_background

can_capitalize

canvas_bg

check_font_styles(self, interval: int | float = 0)

update_font_style(self, instance_label, font_style: str)

do_selection(self)

cancel_selection(self)

on_double_tap(self, touch, *args)

Called by double clicking on the widget.

on_window_touch(self, *args)

on_copy(self, *args)

Called when double-tapping on the label.

New in version 1.2.0.

on_selection(self, *args)

Called when double-tapping on the label.

New in version 1.2.0.

on_cancel_selection(self, *args)

Called when the highlighting is removed from the label text.

New in version 1.2.0.

on_allow_selection(self, instance_label, selection: bool)

on_theme_text_color(self, instance_label, theme_text_color: str)

on_text_color(self, instance_label, color: list | str)

on_opposite_colors(self, *args)

on_md_bg_color(self, instance_label, color: list | str)

Called when the values of md_bg_color change.

on_size(self, instance_label, size: list)

update_canvas_bg_pos(self, instance_label, pos: list)

class kivymd.uix.label.label.MDIcon(*args, **kwargs)

Icon class.

For more information, see in the MDLabel and MDFloatLayout classes documentation.

icon

Label icon name.

icon is an StringProperty and defaults to ‘android’.

badge_icon

Label badge icon name.

New in version 1.0.0.

badge_icon is an StringProperty and defaults to ‘’.

badge_icon_color

Badge icon color in (r, g, b, a) or string format.

New in version 1.0.0.

badge_icon_color is an ColorProperty and defaults to None.

badge_bg_color

Badge icon background color in (r, g, b, a) or string format.

New in version 1.0.0.

badge_bg_color is an ColorProperty and defaults to None.

badge_font_size

Badge font size.

New in version 1.0.0.

badge_font_size is an NumericProperty and defaults to 0.

source

Path to icon.

source is an StringProperty and defaults to None.

adjust_size(self, *args)