Card#

Cards contain content and actions about a single subject.

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

KivyMD provides the following card classes for use:

Note

MDCard inherited from BoxLayout. You can use all parameters and attributes of the BoxLayout class in the MDCard class.

MDCard#

Warning

Starting from the KivyMD 1.0.0 library version, it is necessary to manually inherit the card class from one of the Elevation classes from kivymd/uix/behaviors/elevation.py module to draw the card shadow.

from kivymd.uix.behaviors import RoundedRectangularElevationBehavior
from kivymd.uix.card import MDCard


class MD3Card(MDCard, RoundedRectangularElevationBehavior):
    '''Implements a material design v3 card.'''

This may sound awkward to you, but it actually allows for better control over the providers that implement the rendering of the shadows.

Note

You can read more information about the classes that implement the rendering of shadows on this documentation page.

An example of the implementation of a card in the style of material design version 3#

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

from kivymd.app import MDApp
from kivymd.uix.behaviors import RoundedRectangularElevationBehavior
from kivymd.uix.card import MDCard

KV = '''
<MD3Card>
    padding: 16
    size_hint: None, None
    size: "200dp", "100dp"

    MDRelativeLayout:
        size_hint: None, None
        size: root.size

        MDIconButton:
            icon: "dots-vertical"
            pos:
                root.width - (self.width + root.padding[0] + dp(4)),                     root.height - (self.height + root.padding[0] + dp(4))

        MDLabel:
            id: label
            text: root.text
            adaptive_size: True
            color: .2, .2, .2, .8


MDScreen:

    MDBoxLayout:
        id: box
        adaptive_size: True
        spacing: "56dp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class MD3Card(MDCard, RoundedRectangularElevationBehavior):
    '''Implements a material design v3 card.'''

    text = StringProperty()


class TestCard(MDApp):
    def build(self):
        self.theme_cls.material_style = "M3"
        return Builder.load_string(KV)

    def on_start(self):
        styles = {
            "elevated": "#f6eeee", "filled": "#f4dedc", "outlined": "#f8f5f4"
        }
        for style in styles.keys():
            self.root.ids.box.add_widget(
                MD3Card(
                    line_color=(0.2, 0.2, 0.2, 0.8),
                    style=style,
                    text=style.capitalize(),
                    md_bg_color=styles[style],
                )
            )


TestCard().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/cards-m3.png

MDCardSwipe#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/MDCardSwipe.gif

To create a card with swipe-to-delete behavior, you must create a new class that inherits from the MDCardSwipe class:

<SwipeToDeleteItem>:
    size_hint_y: None
    height: content.height

    MDCardSwipeLayerBox:

    MDCardSwipeFrontBox:

        OneLineListItem:
            id: content
            text: root.text
            _no_ripple_effect: True
class SwipeToDeleteItem(MDCardSwipe):
    text = StringProperty()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/map-mdcard-swipr.png

End full code#

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

from kivymd.app import MDApp
from kivymd.uix.card import MDCardSwipe

KV = '''
<SwipeToDeleteItem>:
    size_hint_y: None
    height: content.height

    MDCardSwipeLayerBox:
        # Content under the card.

    MDCardSwipeFrontBox:

        # Content of card.
        OneLineListItem:
            id: content
            text: root.text
            _no_ripple_effect: True


MDScreen:

    MDBoxLayout:
        orientation: "vertical"
        spacing: "10dp"

        MDTopAppBar:
            elevation: 10
            title: "MDCardSwipe"

        ScrollView:
            scroll_timeout : 100

            MDList:
                id: md_list
                padding: 0
'''


class SwipeToDeleteItem(MDCardSwipe):
    '''Card with `swipe-to-delete` behavior.'''

    text = StringProperty()


class TestCard(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)

    def build(self):
        return self.screen

    def on_start(self):
        '''Creates a list of cards.'''

        for i in range(20):
            self.screen.ids.md_list.add_widget(
                SwipeToDeleteItem(text=f"One-line item {i}")
            )


TestCard().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/list-mdcard-swipe.gif

Binding a swipe to one of the sides of the screen#

<SwipeToDeleteItem>:
    # By default, the parameter is "left"
    anchor: "right"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mdcard-swipe-anchor-right.gif

Note

You cannot use the left and right swipe at the same time.

Swipe behavior#

<SwipeToDeleteItem>:
    # By default, the parameter is "hand"
    type_swipe: "hand"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hand-mdcard-swipe.gif
<SwipeToDeleteItem>:
    type_swipe: "auto"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/auto-mdcard-swipe.gif

Removing an item using the type_swipe = "auto" parameter#

The map provides the MDCardSwipe.on_swipe_complete event. You can use this event to remove items from a list:

<SwipeToDeleteItem>:
    on_swipe_complete: app.on_swipe_complete(root)
def on_swipe_complete(self, instance):
    self.screen.ids.md_list.remove_widget(instance)

End full code#

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

from kivymd.app import MDApp
from kivymd.uix.card import MDCardSwipe

KV = '''
<SwipeToDeleteItem>:
    size_hint_y: None
    height: content.height
    type_swipe: "auto"
    on_swipe_complete: app.on_swipe_complete(root)

    MDCardSwipeLayerBox:

    MDCardSwipeFrontBox:

        OneLineListItem:
            id: content
            text: root.text
            _no_ripple_effect: True


MDScreen:

    MDBoxLayout:
        orientation: "vertical"
        spacing: "10dp"

        MDTopAppBar:
            elevation: 10
            title: "MDCardSwipe"

        ScrollView:

            MDList:
                id: md_list
                padding: 0
'''


class SwipeToDeleteItem(MDCardSwipe):
    text = StringProperty()


class TestCard(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)

    def build(self):
        return self.screen

    def on_swipe_complete(self, instance):
        self.screen.ids.md_list.remove_widget(instance)

    def on_start(self):
        for i in range(20):
            self.screen.ids.md_list.add_widget(
                SwipeToDeleteItem(text=f"One-line item {i}")
            )


TestCard().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/autodelete-mdcard-swipe.gif

Add content to the bottom layer of the card#

To add content to the bottom layer of the card, use the MDCardSwipeLayerBox class.

<SwipeToDeleteItem>:

    MDCardSwipeLayerBox:
        padding: "8dp"

        MDIconButton:
            icon: "trash-can"
            pos_hint: {"center_y": .5}
            on_release: app.remove_item(root)

End full code#

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

from kivymd.app import MDApp
from kivymd.uix.card import MDCardSwipe

KV = '''
<SwipeToDeleteItem>:
    size_hint_y: None
    height: content.height

    MDCardSwipeLayerBox:
        padding: "8dp"

        MDIconButton:
            icon: "trash-can"
            pos_hint: {"center_y": .5}
            on_release: app.remove_item(root)

    MDCardSwipeFrontBox:

        OneLineListItem:
            id: content
            text: root.text
            _no_ripple_effect: True


MDScreen:

    MDBoxLayout:
        orientation: "vertical"
        spacing: "10dp"

        MDTopAppBar:
            elevation: 10
            title: "MDCardSwipe"

        ScrollView:

            MDList:
                id: md_list
                padding: 0
'''


class SwipeToDeleteItem(MDCardSwipe):
    text = StringProperty()


class TestCard(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)

    def build(self):
        return self.screen

    def remove_item(self, instance):
        self.screen.ids.md_list.remove_widget(instance)

    def on_start(self):
        for i in range(20):
            self.screen.ids.md_list.add_widget(
                SwipeToDeleteItem(text=f"One-line item {i}")
            )


TestCard().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/handdelete-mdcard-swipe.gif

Focus behavior#

MDCard:
    focus_behavior: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-focus.gif

Ripple behavior#

MDCard:
    ripple_behavior: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-behavior.gif

End full code#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<StarButton@MDIconButton>
    icon: "star"
    on_release: self.icon = "star-outline" if self.icon == "star" else "star"


MDScreen:

    MDCard:
        orientation: "vertical"
        size_hint: .5, None
        height: box_top.height + box_bottom.height
        focus_behavior: True
        ripple_behavior: True
        pos_hint: {"center_x": .5, "center_y": .5}

        MDBoxLayout:
            id: box_top
            spacing: "20dp"
            adaptive_height: True

            FitImage:
                source: "/Users/macbookair/album.jpeg"
                size_hint: .3, None
                height: text_box.height

            MDBoxLayout:
                id: text_box
                orientation: "vertical"
                adaptive_height: True
                spacing: "10dp"
                padding: 0, "10dp", "10dp", "10dp"

                MDLabel:
                    text: "Ride the Lightning"
                    theme_text_color: "Primary"
                    font_style: "H5"
                    bold: True
                    adaptive_height: True

                MDLabel:
                    text: "July 27, 1984"
                    adaptive_height: True
                    theme_text_color: "Primary"

        MDSeparator:

        MDBoxLayout:
            id: box_bottom
            adaptive_height: True
            padding: "10dp", 0, 0, 0

            MDLabel:
                text: "Rate this album"
                adaptive_height: True
                pos_hint: {"center_y": .5}
                theme_text_color: "Primary"

            StarButton:
            StarButton:
            StarButton:
            StarButton:
            StarButton:
'''


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


Test().run()

API - kivymd.uix.card.card#

class kivymd.uix.card.card.MDSeparator(**kwargs)#

A separator line.

color#

Separator color in rgba format.

color is a ColorProperty and defaults to None.

on_orientation(self, *args)#
class kivymd.uix.card.card.MDCard(**kwargs)#

Common base class for rectangular and circular elevation behavior.

focus_behavior#

Using focus when hovering over a card.

focus_behavior is a BooleanProperty and defaults to False.

ripple_behavior#

Use ripple effect for card.

ripple_behavior is a BooleanProperty and defaults to False.

elevation#

Elevation value.

elevation is an NumericProperty and defaults to 1.

radius#

Card radius by default.

New in version 1.0.0.

radius is an VariableListProperty and defaults to [dp(6), dp(6), dp(6), dp(6)].

style#

Card type.

New in version 1.0.0.

Available options are: ‘filled’, ‘elevated’, ‘outlined’.

style is an OptionProperty and defaults to ‘elevated’.

update_md_bg_color(self, instance_card, theme_style: str)#
set_style(self, *args)#
set_line_color(self)#
set_elevation(self)#
set_radius(self)#
on_ripple_behavior(self, interval: Union[int, float], value_behavior: bool)#
class kivymd.uix.card.card.MDCardSwipe(**kw)#
Events:

on_swipe_complete

Called when a swipe of card is completed.

open_progress#

Percent of visible part of side panel. The percent is specified as a floating point number in the range 0-1. 0.0 if panel is closed and 1.0 if panel is opened.

open_progress is a NumericProperty and defaults to 0.0.

opening_transition#

The name of the animation transition type to use when animating to the state ‘opened’.

opening_transition is a StringProperty and defaults to ‘out_cubic’.

closing_transition#

The name of the animation transition type to use when animating to the state ‘closed’.

closing_transition is a StringProperty and defaults to ‘out_sine’.

anchor#

Anchoring screen edge for card. Available options are: ‘left’, ‘right’.

anchor is a OptionProperty and defaults to left.

swipe_distance#

The distance of the swipe with which the movement of navigation drawer begins.

swipe_distance is a NumericProperty and defaults to 50.

opening_time#

The time taken for the card to slide to the state ‘open’.

opening_time is a NumericProperty and defaults to 0.2.

state#

Detailed state. Sets before state. Bind to state instead of status. Available options are: ‘closed’, ‘opened’.

status is a OptionProperty and defaults to ‘closed’.

max_swipe_x#

If, after the events of on_touch_up card position exceeds this value - will automatically execute the method open_card, and if not - will automatically be close_card method.

max_swipe_x is a NumericProperty and defaults to 0.3.

max_opened_x#

The value of the position the card shifts to when type_swipe s set to ‘hand’.

max_opened_x is a NumericProperty and defaults to 100dp.

type_swipe#

Type of card opening when swipe. Shift the card to the edge or to a set position max_opened_x. Available options are: ‘auto’, ‘hand’.

type_swipe is a OptionProperty and defaults to auto.

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

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)
on_swipe_complete(self, *args)#

Called when a swipe of card is completed.

on_anchor(self, instance_swipe_to_delete_item, anchor_value: str)#
on_open_progress(self, instance_swipe_to_delete_item, progress_value: float)#
on_touch_move(self, touch)#

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.

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.

complete_swipe(self)#
open_card(self)#
close_card(self)#
class kivymd.uix.card.card.MDCardSwipeFrontBox(**kwargs)#

Common base class for rectangular and circular elevation behavior.

class kivymd.uix.card.card.MDCardSwipeLayerBox(*args, **kwargs)#

Box layout class. For more information, see in the BoxLayout class documentation.