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#

There are three types of cards: elevated, filled, and outlined:

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

  2. Filled card

  3. Outlined card

Example#

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

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

KV = '''
<MyCard>
    padding: "4dp"
    size_hint: None, None
    size: "240dp", "100dp"

    MDRelativeLayout:

        MDIconButton:
            icon: "dots-vertical"
            pos_hint: {"top": 1, "right": 1}

        MDLabel:
            text: root.text
            adaptive_size: True
            color: "grey"
            pos: "12dp", "12dp"
            bold: True


MDScreen:
    theme_bg_color: "Custom"
    md_bg_color: self.theme_cls.backgroundColor

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


class MyCard(MDCard):
    '''Implements a material card.'''

    text = StringProperty()


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)

    def on_start(self):
        super().on_start()
        for style in ("elevated", "filled", "outlined"):
            self.root.ids.box.add_widget(
                MyCard(style=style, text=style.capitalize())
            )


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-usage.png

Elevated#

MDCard
    style: "elevated"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-elevated.png

Filled#

MDCard
    style: "filled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-filled.png

Outlined#

MDCard
    style: "outlined"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-outlined.png

Customization of card#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    theme_bg_color: "Custom"
    md_bg_color: self.theme_cls.backgroundColor

    MDCard:
        style: "elevated"
        pos_hint: {"center_x": .5, "center_y": .5}
        padding: "4dp"
        size_hint: None, None
        size: "240dp", "100dp"
        # Sets custom properties.
        theme_shadow_color: "Custom"
        shadow_color: "green"
        theme_bg_color: "Custom"
        md_bg_color: "white"
        md_bg_color_disabled: "grey"
        theme_shadow_offset: "Custom"
        shadow_offset: (1, -2)
        theme_shadow_softness: "Custom"
        shadow_softness: 1
        theme_elevation_level: "Custom"
        elevation_level: 2

        MDRelativeLayout:

            MDIconButton:
                icon: "dots-vertical"
                pos_hint: {"top": 1, "right": 1}

            MDLabel:
                text: "Elevated"
                adaptive_size: True
                color: "grey"
                pos: "12dp", "12dp"
                bold: True
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/card-customization.png

MDCardSwipe#

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/sceleton-mdcard-swiper.png

Example#

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:

    MDScrollView:

        MDList:
            id: md_list
            padding: 0
'''


class SwipeToDeleteItem(MDCardSwipe):
    text = StringProperty()


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        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):
        super().on_start()
        for i in range(20):
            self.screen.ids.md_list.add_widget(
                SwipeToDeleteItem(text=f"One-line item {i}")
            )


Example().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"  # "auto"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hand-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.root.ids.md_list.remove_widget(instance)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/auto-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)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mdcard-swipe-content.png

API - kivymd.uix.card.card#

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

Card class.

For more information, see in the DeclarativeBehavior and MDAdaptiveWidget and ThemableBehavior and BackgroundColorBehavior and CommonElevationBehavior and RectangularRippleBehavior and StateLayerBehavior and ButtonBehavior and BoxLayout and classes documentation.

ripple_behavior#

Use ripple effect for card.

ripple_behavior is a BooleanProperty and defaults to False.

radius#

Card radius by default.

New in version 1.0.0.

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

style#

Card type.

New in version 1.0.0.

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

style is an OptionProperty and defaults to None.

md_bg_color_disabled#

The background color in (r, g, b, a) or string format of the card when the card is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

on_press(*args) None#

Fired when the button is pressed.

on_release(*args) None#

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

on_ripple_behavior(interval: int | float, value: bool) None#

Fired when the ripple_behavior value changes.

set_properties_widget() None#

Fired on_release/on_press/on_enter/on_leave events.

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

Card swipe class.

For more information, see in the MDRelativeLayout class documentation.

Events:
on_swipe_complete

Fired 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’.

closing_interval#

Interval for closing the front layer.

New in version 1.1.0.

closing_interval is a NumericProperty and defaults to 0.

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.

on_swipe_complete(*args)#

Fired when a swipe of card is completed.

on_anchor(instance_swipe_to_delete_item, anchor_value: str) None#

Fired when the value of anchor changes.

on_open_progress(instance_swipe_to_delete_item, progress_value: float) None#

Fired when the value of open_progress changes.

on_touch_move(touch)#

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

See on_touch_down() for more information.

on_touch_up(touch)#

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

See on_touch_down() for more information.

on_touch_down(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.

open_card() None#

Animates the opening of the card.

close_card(*args) None#

Animates the closing of the card.

add_widget(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)
class kivymd.uix.card.card.MDCardSwipeFrontBox(*args, **kwargs)#

Card swipe front box.

For more information, see in the MDCard class documentation.

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

Card swipe back box.

For more information, see in the MDBoxLayout class documentation.