Label#

The MDLabel widget is for rendering text.

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

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:

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-to-left.png

Note

See halign and valign attributes of the Label class

MDLabel:
    text: "MDLabel"
    halign: "center"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-to-center.png

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-theme-text-color.png

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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-custom-color.png

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-font-style.png

Highlighting and copying labels#

You can highlight labels by double tap on the label:#

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-label-allow-selection.gif

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

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/copying-cutting-labels-using-context-menu.gif

MDIcon#

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

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}
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-icon.png

MDIcon with badge icon#

MDIcon:
    icon: "gmail"
    badge_icon: "numeric-10"
    pos_hint: {"center_x": .5, "center_y": .5}
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-icon-badge.png

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