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

Usage

from kivy.lang import Builder

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

KV = '''
ScrollView:

    MDList:
        id: container
'''


class Test(MDApp):
    def build(self):
        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}")
            )

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

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

    ImageLeftWidget:
        source: "data/logo/kivy-icon-256.png"

TwoLineAvatarListItem

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

    ImageLeftWidget:
        source: "data/logo/kivy-icon-256.png"

ThreeLineAvatarListItem

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

    ImageLeftWidget:
        source: "data/logo/kivy-icon-256.png"

OneLineIconListItem

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

    IconLeftWidget:
        icon: "language-python"

TwoLineIconListItem

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

    IconLeftWidget:
        icon: "language-python"

ThreeLineIconListItem

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

    IconLeftWidget:
        icon: "language-python"

OneLineAvatarIconListItem

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

    IconLeftWidget:
        icon: "plus"

    IconRightWidget:
        icon: "minus"

TwoLineAvatarIconListItem

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

    IconLeftWidget:
        icon: "plus"

    IconRightWidget:
        icon: "minus"

ThreeLineAvatarIconListItem

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

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:


BoxLayout:

    ScrollView:

        MDList:
            id: scroll
'''


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

    icon = StringProperty("android")


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


class MainApp(MDApp):
    def build(self):
        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])
            )


MainApp().run()

API - kivymd.uix.list

class kivymd.uix.list.MDList

Bases: kivy.uix.gridlayout.GridLayout

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.

add_widget(self, widget, index=0, canvas=None)

remove_widget(self, widget)

class kivymd.uix.list.BaseListItem

Bases: kivymd.theming.ThemableBehavior, kivymd.uix.behaviors.RectangularRippleBehavior, kivy.uix.behaviors.ButtonBehavior, kivy.uix.floatlayout.FloatLayout

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

text

Text shown in the first line.

text is a StringProperty and defaults to ‘’.

text_color

Text color in rgba format used if theme_text_color is set to ‘Custom’.

text_color is a ListProperty and defaults to None.

font_style

Text font style. See kivymd.font_definitions.py.

font_style is a OptionProperty and defaults to ‘Subtitle1’.

theme_text_color

Theme text color in rgba format for 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 rgba format used for secondary text if secondary_theme_text_color is set to ‘Custom’.

secondary_text_color is a ListProperty and defaults to None.

tertiary_text_color

Text color in rgba format used for tertiary text if secondary_theme_text_color is set to ‘Custom’.

tertiary_text_color is a ListProperty and defaults to None.

secondary_theme_text_color

Theme text color for secondary text.

secondary_theme_text_color is a StringProperty and defaults to ‘Secondary’.

tertiary_theme_text_color

Theme text color for tertiary text.

tertiary_theme_text_color is a StringProperty and defaults to ‘Secondary’.

secondary_font_style

Font style for secondary line. See kivymd.font_definitions.py.

secondary_font_style is a OptionProperty and defaults to ‘Body1’.

tertiary_font_style

Font style for tertiary line. See kivymd.font_definitions.py.

tertiary_font_style is a OptionProperty and defaults to ‘Body1’.

divider

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

tertiary_font_style is a OptionProperty and defaults to ‘Body1’.

bg_color

Background color for menu item.

bg_color is a ListProperty and defaults to [].

class kivymd.uix.list.ILeftBody

Pseudo-interface for widgets that go in the left container for ListItems that support it.

Implements nothing and requires no implementation, for annotation only.

class kivymd.uix.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.IRightBody

Pseudo-interface for widgets that go in the right container for ListItems that support it.

Implements nothing and requires no implementation, for annotation only.

class kivymd.uix.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.ContainerSupport

Overrides add_widget in a ListItem to include support for I*Body widgets when the appropiate containers are present.

add_widget(self, widget, index=0)

remove_widget(self, widget)

on_touch_down(self, touch)

on_touch_move(self, touch, *args)

on_touch_up(self, touch)

propagate_touch_to_touchable_widgets(self, touch, touch_event, *args)

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

Bases: kivymd.uix.list.BaseListItem

A one line list item.

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

Bases: kivymd.uix.list.BaseListItem

A two line list item.

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

Bases: kivymd.uix.list.BaseListItem

A three line list item.

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

Bases: kivymd.uix.list.ContainerSupport, kivymd.uix.list.BaseListItem

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

Bases: kivymd.uix.list.OneLineAvatarListItem

class kivymd.uix.list.ThreeLineAvatarListItem

Bases: kivymd.uix.list.ContainerSupport, kivymd.uix.list.ThreeLineListItem

class kivymd.uix.list.OneLineIconListItem

Bases: kivymd.uix.list.ContainerSupport, kivymd.uix.list.OneLineListItem

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

Bases: kivymd.uix.list.OneLineIconListItem

class kivymd.uix.list.ThreeLineIconListItem

Bases: kivymd.uix.list.ContainerSupport, kivymd.uix.list.ThreeLineListItem

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

Bases: kivymd.uix.list.ContainerSupport, kivymd.uix.list.OneLineListItem

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

Bases: kivymd.uix.list.OneLineRightIconListItem

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

Bases: kivymd.uix.list.ContainerSupport, kivymd.uix.list.ThreeLineListItem

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

Bases: kivymd.uix.list.OneLineAvatarListItem

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

Bases: kivymd.uix.list.TwoLineAvatarListItem

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

Bases: kivymd.uix.list.ThreeLineAvatarListItem

class kivymd.uix.list.ImageLeftWidget

Bases: kivymd.uix.list.ILeftBody, kivy.uix.image.Image

class kivymd.uix.list.ImageRightWidget

Bases: kivymd.uix.list.IRightBodyTouch, kivy.uix.image.Image

class kivymd.uix.list.IconRightWidget

Bases: kivymd.uix.list.IRightBodyTouch, kivymd.uix.button.MDIconButton

class kivymd.uix.list.IconLeftWidget

Bases: kivymd.uix.list.ILeftBodyTouch, kivymd.uix.button.MDIconButton