List

See also

Material Design spec, Lists

Lists are continuous, vertical indexes of text or images.

The class MDList in combination with a BaseListItem like OneLineListItem will create a list that expands as items are added to it, working nicely with Kivy’s ScrollView.

Due to the variety in sizes and controls in the Material Design spec, this module suffers from a certain level of complexity to keep the widgets compliant, flexible and performant.

For this KivyMD provides list items that try to cover the most common usecases, when those are insufficient, there’s a base class called BaseListItem which you can use to create your own list items. This documentation will only cover the provided ones, for custom implementations please refer to this module’s source code.

KivyMD provides the following list items classes for use:

Text only ListItems

• OneLineListItem

• TwoLineListItem

• ThreeLineListItem

ListItems with widget containers

These widgets will take other widgets that inherit from ILeftBody, ILeftBodyTouch, IRightBody or IRightBodyTouch and put them in their corresponding container.

As the name implies, ILeftBody and IRightBody will signal that the widget goes into the left or right container, respectively.

ILeftBodyTouch and IRightBodyTouch do the same thing, except these widgets will also receive touch events that occur within their surfaces.

KivyMD provides base classes such as ImageLeftWidget, ImageRightWidget, IconRightWidget, IconLeftWidget, based on the above classes.

Allows the use of items with custom widgets on the left.

• OneLineAvatarListItem

• TwoLineAvatarListItem

• ThreeLineAvatarListItem

• OneLineIconListItem

• TwoLineIconListItem

• ThreeLineIconListItem

It allows the use of elements with custom widgets on the left and the right.

• OneLineAvatarIconListItem

• TwoLineAvatarIconListItem

• ThreeLineAvatarIconListItem

• OneLineRightIconListItem

• TwoLineRightIconListItem

• ThreeLineRightIconListItem

Usage

Declarative KV styleDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.list import OneLineListItem

KV = '''
MDScrollView:

    MDList:
        id: container
'''


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

    def on_start(self):
        for i in range(20):
            self.root.ids.container.add_widget(
                OneLineListItem(text=f"Single-line item {i}")
            )

Example().run()

Events of List

Declarative KV styleDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScrollView:

    MDList:

        OneLineAvatarIconListItem:
            on_release: print("Click!")

            IconLeftWidget:
                icon: "github"

        OneLineAvatarIconListItem:
            on_release: print("Click 2!")

            IconLeftWidget:
                icon: "gitlab"
'''


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


Example().run()

OneLineListItem

OneLineListItem:
    text: "Single-line item"

TwoLineListItem

TwoLineListItem:
    text: "Two-line item"
    secondary_text: "Secondary text here"

ThreeLineListItem

ThreeLineListItem:
    text: "Three-line item"
    secondary_text: "This is a multi-line label where you can"
    tertiary_text: "fit more text than usual"

OneLineAvatarListItem

Declarative KV styleDeclarative python style

OneLineAvatarListItem:
    text: "Single-line item with avatar"

    ImageLeftWidget:
        source: "kivymd/images/logo/kivymd-icon-256.png"

TwoLineAvatarListItem

Declarative KV styleDeclarative python style

TwoLineAvatarListItem:
    text: "Two-line item with avatar"
    secondary_text: "Secondary text here"

    ImageLeftWidget:
        source: "kivymd/images/logo/kivymd-icon-256.png"

ThreeLineAvatarListItem

Declarative KV styleDeclarative python style

ThreeLineAvatarListItem:
    text: "Three-line item with avatar"
    secondary_text: "Secondary text here"
    tertiary_text: "fit more text than usual"

    ImageLeftWidget:
        source: "kivymd/images/logo/kivymd-icon-256.png"

OneLineRightIconListItem

Declarative KV styleDeclarative python style

OneLineRightIconListItem:
    text: "Single-line item with avatar"

    ImageRightWidget:
        source: "kivymd/images/logo/kivymd-icon-256.png"

TwoLineRightIconListItem

Declarative KV styleDeclarative python style

TwoLineRightIconListItem:
    text: "Single-line item with avatar"
    secondary_text: "Secondary text here"

    ImageRightWidget:
        source: "kivymd/images/logo/kivymd-icon-256.png"

ThreeLineRightIconListItem

Declarative KV styleDeclarative python style

ThreeLineRightIconListItem:
    text: "Single-line item with avatar"
    secondary_text: "Secondary text here"
    tertiary_text: "fit more text than usual"

    ImageRightWidget:
        source: "kivymd/images/logo/kivymd-icon-256.png"

OneLineIconListItem

Declarative KV styleDeclarative python style

OneLineIconListItem:
    text: "Single-line item with avatar"

    IconLeftWidget:
        icon: "language-python"

TwoLineIconListItem

Declarative KV styleDeclarative python style

TwoLineIconListItem:
    text: "Two-line item with avatar"
    secondary_text: "Secondary text here"

    IconLeftWidget:
        icon: "language-python"

ThreeLineIconListItem

Declarative KV styleDeclarative python style

ThreeLineIconListItem:
    text: "Three-line item with avatar"
    secondary_text: "Secondary text here"
    tertiary_text: "fit more text than usual"

    IconLeftWidget:
        icon: "language-python"

OneLineAvatarIconListItem

Declarative KV styleDeclarative python style

OneLineAvatarIconListItem:
    text: "One-line item with avatar"

    IconLeftWidget:
        icon: "plus"

    IconRightWidget:
        icon: "minus"

TwoLineAvatarIconListItem

Declarative KV styleDeclarative python style

TwoLineAvatarIconListItem:
    text: "Two-line item with avatar"
    secondary_text: "Secondary text here"

    IconLeftWidget:
        icon: "plus"

    IconRightWidget:
        icon: "minus"

ThreeLineAvatarIconListItem

Declarative KV styleDeclarative python style

ThreeLineAvatarIconListItem:
    text: "Three-line item with avatar"
    secondary_text: "Secondary text here"
    tertiary_text: "fit more text than usual"

    IconLeftWidget:
        icon: "plus"

    IconRightWidget:
        icon: "minus"

Custom list item

Declarative KV styleDeclarative python style

from kivy.lang import Builder
from kivy.properties import StringProperty

from kivymd.app import MDApp
from kivymd.uix.list import IRightBodyTouch, OneLineAvatarIconListItem
from kivymd.uix.selectioncontrol import MDCheckbox
from kivymd.icon_definitions import md_icons


KV = '''
<ListItemWithCheckbox>:

    IconLeftWidget:
        icon: root.icon

    RightCheckbox:


MDScrollView:

    MDList:
        id: scroll
'''


class ListItemWithCheckbox(OneLineAvatarIconListItem):
    '''Custom list item.'''

    icon = StringProperty("android")


class RightCheckbox(IRightBodyTouch, MDCheckbox):
    '''Custom right container.'''


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

    def on_start(self):
        icons = list(md_icons.keys())
        for i in range(30):
            self.root.ids.scroll.add_widget(
                ListItemWithCheckbox(text=f"Item {i}", icon=icons[i])
            )


Example().run()

Declarative KV styleDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.list import IRightBodyTouch

KV = '''
OneLineAvatarIconListItem:
    text: "One-line item with avatar"
    on_size:
        self.ids._right_container.width = container.width
        self.ids._right_container.x = container.width

    IconLeftWidget:
        icon: "cog"

    YourContainer:
        id: container

        MDIconButton:
            icon: "minus"

        MDIconButton:
            icon: "plus"
'''


class YourContainer(IRightBodyTouch, MDBoxLayout):
    adaptive_width = True


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


Example().run()

Behavior

When using the AvatarListItem and IconListItem classes, when an icon is clicked, the event of this icon is triggered:

Declarative KV styleDeclarative python style

OneLineIconListItem:
    text: "Single-line item with icon"

    IconLeftWidget:
        icon: "language-python"

You can disable the icon event using the WithoutTouch classes:

Declarative KV styleDeclarative python style

OneLineIconListItem:
    text: "Single-line item with icon"

    IconLeftWidgetWithoutTouch:
        icon: "language-python"

API - kivymd.uix.list.list

class kivymd.uix.list.list.MDList(*args, **kwargs)

ListItem container. Best used in conjunction with a kivy.uix.ScrollView.

When adding (or removing) a widget, it will resize itself to fit its children, plus top and bottom paddings as described by the MD spec.

For more information, see in the MDGridLayout classes documentation.

class kivymd.uix.list.list.BaseListItem(*args, **kwargs)

Base class to all ListItems. Not supposed to be instantiated on its own.

For more information, see in the DeclarativeBehavior and ThemableBehavior and RectangularRippleBehavior and ButtonBehavior and FloatLayout classes documentation.

text

Text shown in the first line.

text is a StringProperty and defaults to ‘’.

text_color

Text color in (r, g, b, a) or string format used if theme_text_color is set to ‘Custom’.

text_color is a ColorProperty and defaults to None.

font_style

Text font style. See font-definitions for more information.

font_style is a StringProperty and defaults to ‘Subtitle1’.

theme_text_color

The name of the color scheme for for the primary text.

theme_text_color is a StringProperty and defaults to ‘Primary’.

secondary_text

Text shown in the second line.

secondary_text is a StringProperty and defaults to ‘’.

tertiary_text

The text is displayed on the third line.

tertiary_text is a StringProperty and defaults to ‘’.

secondary_text_color

Text color in (r, g, b, a) or string format used for secondary text if secondary_theme_text_color is set to ‘Custom’.

secondary_text_color is a ColorProperty and defaults to None.

tertiary_text_color

Text color in (r, g, b, a) or string format used for tertiary text if tertiary_theme_text_color is set to ‘Custom’.

tertiary_text_color is a ColorProperty and defaults to None.

secondary_theme_text_color

The name of the color scheme for for the secondary text.

secondary_theme_text_color is a StringProperty and defaults to ‘Secondary’.

tertiary_theme_text_color

The name of the color scheme for for the tertiary text.

tertiary_theme_text_color is a StringProperty and defaults to ‘Secondary’.

secondary_font_style

Font style for secondary line. See font-definitions for more information.

secondary_font_style is a StringProperty and defaults to ‘Body1’.

tertiary_font_style

Font style for tertiary line. See font-definitions for more information.

tertiary_font_style is a StringProperty and defaults to ‘Body1’.

divider

Divider mode. Available options are: ‘Full’, ‘Inset’ and default to ‘Full’.

divider is a OptionProperty and defaults to ‘Full’.

divider_color

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

New in version 1.0.0.

divider_color is a ColorProperty and defaults to None.

bg_color

Background color for list item in (r, g, b, a) or string format.

bg_color is a ColorProperty and defaults to None.

radius

Canvas radius.

# Top left corner slice.
MDBoxLayout:
    md_bg_color: app.theme_cls.primary_color
    radius: [25, 0, 0, 0]

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

on_touch_down(self, touch)

Receive a touch down event.

Parameters:

touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_move(self, touch, *args)

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(self, touch)

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

propagate_touch_to_touchable_widgets(self, touch, touch_event, *args)

add_widget(self, widget)

Add a new widget as a child of this widget.

Parameters:

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

remove_widget(self, widget)

Remove a widget from the children of this widget.

Parameters:

widget: Widget

Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

class kivymd.uix.list.list.ILeftBodyTouch

Same as ILeftBody, but allows the widget to receive touch events instead of triggering the ListItem’s ripple effect.

class kivymd.uix.list.list.IRightBodyTouch

Same as IRightBody, but allows the widget to receive touch events instead of triggering the ListItem’s ripple effect

class kivymd.uix.list.list.OneLineListItem(*args, **kwargs)

A one line list item.

For more information, see in the BaseListItem classes documentation.

class kivymd.uix.list.list.TwoLineListItem(**kwargs)

A two line list item.

For more information, see in the BaseListItem classes documentation.

class kivymd.uix.list.list.ThreeLineListItem(*args, **kwargs)

A three line list item.

For more information, see in the BaseListItem classes documentation.

class kivymd.uix.list.list.OneLineAvatarListItem(*args, **kwargs)

A one line list item with left image.

For more information, see in the BaseListItem classes documentation.

class kivymd.uix.list.list.TwoLineAvatarListItem(*args, **kwargs)

A two line list item with left image.

For more information, see in the OneLineAvatarListItem classes documentation.

class kivymd.uix.list.list.ThreeLineAvatarListItem(*args, **kwargs)

A three line list item with left image.

For more information, see in the ThreeLineListItem classes documentation.

class kivymd.uix.list.list.OneLineIconListItem(*args, **kwargs)

A one line list item with left icon.

For more information, see in the OneLineListItem classes documentation.

class kivymd.uix.list.list.TwoLineIconListItem(*args, **kwargs)

A two line list item with left icon.

For more information, see in the OneLineIconListItem classes documentation.

class kivymd.uix.list.list.ThreeLineIconListItem(*args, **kwargs)

A three line list item with left icon.

For more information, see in the ThreeLineListItem classes documentation.

class kivymd.uix.list.list.OneLineRightIconListItem(*args, **kwargs)

A one line list item with right icon/image.

For more information, see in the OneLineListItem classes documentation.

class kivymd.uix.list.list.TwoLineRightIconListItem(**kwargs)

A two line list item with right icon/image.

For more information, see in the OneLineRightIconListItem classes documentation.

class kivymd.uix.list.list.ThreeLineRightIconListItem(**kwargs)

A three line list item with right icon/image.

For more information, see in the ThreeLineRightIconListItem classes documentation.

class kivymd.uix.list.list.OneLineAvatarIconListItem(*args, **kwargs)

A one line list item with left/right icon/image/widget.

For more information, see in the OneLineAvatarListItem classes documentation.

class kivymd.uix.list.list.TwoLineAvatarIconListItem(*args, **kwargs)

A two line list item with left/right icon/image/widget.

For more information, see in the TwoLineAvatarListItem classes documentation.

class kivymd.uix.list.list.ThreeLineAvatarIconListItem(*args, **kwargs)

A three line list item with left/right icon/image/widget.

For more information, see in the ThreeLineAvatarListItem classes documentation.

class kivymd.uix.list.list.ImageLeftWidget(**kwargs)

The widget implements the left image for use in ListItem classes.

For more information, see in the CircularRippleBehavior and ButtonBehavior and ILeftBodyTouch and FitImage classes documentation.

class kivymd.uix.list.list.ImageLeftWidgetWithoutTouch(**kwargs)

Disables the image event. The widget implements the left image for use in ListItem classes.

For more information, see in the CircularRippleBehavior and TouchBehavior and ButtonBehavior and ILeftBody and FitImage classes documentation.

New in version 1.0.0.

class kivymd.uix.list.list.ImageRightWidget(**kwargs)

The widget implements the right image for use in ListItem classes.

For more information, see in the CircularRippleBehavior and ButtonBehavior and IRightBodyTouch and FitImage classes documentation.

class kivymd.uix.list.list.ImageRightWidgetWithoutTouch(**kwargs)

Disables the image event. The widget implements the right image for use in ListItem classes.

For more information, see in the CircularRippleBehavior and TouchBehavior and ButtonBehavior and IRightBody and FitImage classes documentation.

New in version 1.0.0.

class kivymd.uix.list.list.IconRightWidget(*args, **kwargs)

The widget implements the right icon for use in ListItem classes.

For more information, see in the IRightBodyTouch and MDIconButton classes documentation.

pos_hint

class kivymd.uix.list.list.IconRightWidgetWithoutTouch(*args, **kwargs)

Disables the icon event. The widget implements the right icon for use in ListItem classes.

For more information, see in the TouchBehavior and IRightBody and MDIconButton classes documentation.

New in version 1.0.0.

pos_hint

class kivymd.uix.list.list.IconLeftWidget(*args, **kwargs)

The widget implements the left icon for use in ListItem classes.

For more information, see in the ILeftBodyTouch and MDIconButton classes documentation.

pos_hint

class kivymd.uix.list.list.IconLeftWidgetWithoutTouch(*args, **kwargs)

Disables the icon event. The widget implements the left icon for use in ListItem classes.

For more information, see in the TouchBehavior and ILeftBody and MDIconButton classes documentation.

New in version 1.0.0.

pos_hint

class kivymd.uix.list.list.CheckboxLeftWidget(**kwargs)

The widget implements the left checkbox element for use in ListItem classes.

For more information, see in the ILeftBodyTouch and MDCheckbox classes documentation.