Chip#

See also

Material Design spec, Chips

Chips can show multiple interactive elements together in the same area, such as a list of selectable movie times, or a series of email contacts. There are four types of chips: assist, filter, input, and suggestion.

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

Usage#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}

        MDChipText:
            text: "MDChip"
'''


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


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

Anatomy#

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

  1. Container

  2. Label text

  3. Leading icon or image (optional)

  4. Trailing remove icon (optional, input & filter chips only)

Container#

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

All chips are slightly rounded with an 8dp corner.

Shadows and elevation#

Chip containers can be elevated if the placement requires protection, such as on top of an image.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadows-elevation-chip.png

The following types of chips are available:#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/available-type-chips.png

Assist#

Assist chips represent smart or automated actions that can span multiple apps, such as opening a calendar event from the home screen. Assist chips function as though the user asked an assistant to complete the action. They should appear dynamically and contextually in a UI.

An alternative to assist chips are buttons, which should appear persistently and consistently.

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

Example of assist#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<CommonLabel@MDLabel>
    adaptive_size: True
    theme_text_color: "Custom"
    text_color: "#e6e9df"


<CommonAssistChip@MDChip>
    # Custom attribute.
    text: ""
    icon: ""

    # Chip attribute.
    type: "assist"
    md_bg_color: "#2a3127"
    line_color: "grey"
    elevation: 1
    shadow_softness: 2

    MDChipLeadingIcon:
        icon: root.icon
        theme_text_color: "Custom"
        text_color: "#68896c"

    MDChipText:
        text: root.text
        theme_text_color: "Custom"
        text_color: "#e6e9df"


MDScreen:

    FitImage:
        source: "bg.png"

    MDBoxLayout:
        orientation: "vertical"
        adaptive_size: True
        pos_hint: {"center_y": .6, "center_x": .5}

        CommonLabel:
            text: "in 10 mins"
            bold: True
            pos_hint: {"center_x": .5}

        CommonLabel:
            text: "Therapy with Thea"
            font_style: "H3"
            padding_y: "12dp"

        CommonLabel:
            text: "Video call"
            font_style: "H5"
            pos_hint: {"center_x": .5}

        MDBoxLayout:
            adaptive_size: True
            pos_hint: {"center_x": .5}
            spacing: "12dp"
            padding: 0, "24dp", 0, 0

            CommonAssistChip:
                text: "Home office"
                icon: "map-marker"

            CommonAssistChip:
                text: "Chat"
                icon: "message"

        MDWidget:
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-assist-chip.png

Filter#

Filter chips use tags or descriptive words to filter content. They can be a good alternative to toggle buttons or checkboxes.

Tapping on a filter chip activates it and appends a leading checkmark icon to the starting edge of the chip label.

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

Example of filtering#

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

from kivymd.app import MDApp
from kivymd.uix.chip import MDChip, MDChipText
from kivymd.uix.list import OneLineIconListItem
from kivymd.icon_definitions import md_icons
from kivymd.uix.screen import MDScreen
from kivymd.utils import asynckivy

Builder.load_string(
    '''
<CustomOneLineIconListItem>

    IconLeftWidget:
        icon: root.icon


<PreviewIconsScreen>

    MDBoxLayout:
        orientation: "vertical"
        spacing: "14dp"
        padding: "20dp"

        MDTextField:
            id: search_field
            hint_text: "Search icon"
            mode: "rectangle"
            icon_left: "magnify"
            on_text: root.set_list_md_icons(self.text, True)

        MDBoxLayout:
            id: chip_box
            spacing: "12dp"
            adaptive_height: True

        RecycleView:
            id: rv
            viewclass: "CustomOneLineIconListItem"
            key_size: "height"

            RecycleBoxLayout:
                padding: dp(10)
                default_size: None, dp(48)
                default_size_hint: 1, None
                size_hint_y: None
                height: self.minimum_height
                orientation: "vertical"
    '''
)


class CustomOneLineIconListItem(OneLineIconListItem):
    icon = StringProperty()


class PreviewIconsScreen(MDScreen):
    filter = ListProperty()  # list of tags for filtering icons

    def set_filter_chips(self):
        '''Asynchronously creates and adds chips to the container.'''

        async def set_filter_chips():
            for tag in ["Outline", "Off", "On"]:
                await asynckivy.sleep(0)
                chip = MDChip(
                    MDChipText(
                        text=tag,
                    ),
                    type="filter",
                    md_bg_color="#303A29",
                )
                chip.bind(active=lambda x, y, z=tag: self.set_filter(y, z))
                self.ids.chip_box.add_widget(chip)

        asynckivy.start(set_filter_chips())

    def set_filter(self, active: bool, tag: str) -> None:
        '''Sets a list of tags for filtering icons.'''

        if active:
            self.filter.append(tag)
        else:
            self.filter.remove(tag)

    def set_list_md_icons(self, text="", search=False) -> None:
        '''Builds a list of icons.'''

        def add_icon_item(name_icon):
            self.ids.rv.data.append(
                {
                    "icon": name_icon,
                    "text": name_icon,
                }
            )

        self.ids.rv.data = []
        for name_icon in md_icons.keys():
            for tag in self.filter:
                if tag.lower() in name_icon:
                    if search:
                        if text in name_icon:
                            add_icon_item(name_icon)
                    else:
                        add_icon_item(name_icon)


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = PreviewIconsScreen()

    def build(self) -> PreviewIconsScreen:
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "LightGreen"
        return self.screen

    def on_start(self) -> None:
        self.screen.set_list_md_icons()
        self.screen.set_filter_chips()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-filtering-icons-chip.gif

Tap a chip to select it. Multiple chips can be selected or unselected:

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.chip import MDChip, MDChipText
from kivymd.uix.screen import MDScreen
from kivymd.utils import asynckivy

Builder.load_string(
    '''
<ChipScreen>

    MDBoxLayout:
        orientation: "vertical"
        spacing: "14dp"
        padding: "20dp"

        MDLabel:
            adaptive_height: True
            text: "Select Type"

        MDStackLayout:
            id: chip_box
            spacing: "12dp"
            adaptive_height: True

        MDWidget:

    MDFlatButton:
        text: "Uncheck chips"
        pos: "20dp", "20dp"
        on_release: root.unchecks_chips()
    '''
)


class ChipScreen(MDScreen):
    async def create_chips(self):
        '''Asynchronously creates and adds chips to the container.'''

        for tag in ["Extra Soft", "Soft", "Medium", "Hard"]:
            await asynckivy.sleep(0)
            self.ids.chip_box.add_widget(
                MDChip(
                    MDChipText(
                        text=tag,
                    ),
                    type="filter",
                    md_bg_color="#303A29",
                    active=True,
                )
            )

    def unchecks_chips(self) -> None:
        '''Removes marks from all chips.'''

        for chip in self.ids.chip_box.children:
            if chip.active:
                chip.active = False


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = ChipScreen()

    def build(self) -> ChipScreen:
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "LightGreen"
        return self.screen

    def on_start(self) -> None:
        asynckivy.start(self.screen.create_chips())


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-filtering-icons-chip-2.gif

Alternatively, a single chip can be selected. This offers an alternative to toggle buttons, radio buttons, or single select menus:

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.chip import MDChip, MDChipText
from kivymd.uix.screen import MDScreen
from kivymd.utils import asynckivy

Builder.load_string(
    '''
<ChipScreen>

    MDBoxLayout:
        orientation: "vertical"
        spacing: "14dp"
        padding: "20dp"

        MDLabel:
            adaptive_height: True
            text: "Select Type"

        MDStackLayout:
            id: chip_box
            spacing: "12dp"
            adaptive_height: True

        MDFillRoundFlatButton:
            text: "Add to cart"
            md_bg_color: "green"
            size_hint_x: 1

        MDWidget:
    '''
)


class ChipScreen(MDScreen):
    async def create_chips(self):
        '''Asynchronously creates and adds chips to the container.'''

        for tag in ["Extra Soft", "Soft", "Medium", "Hard"]:
            await asynckivy.sleep(0)
            chip = MDChip(
                MDChipText(
                    text=tag,
                ),
                type="filter",
                md_bg_color="#303A29",

            )
            chip.bind(active=self.uncheck_chip)
            self.ids.chip_box.add_widget(chip)

    def uncheck_chip(self, current_chip: MDChip, active: bool) -> None:
        '''Removes a mark from an already marked chip.'''

        if active:
            for chip in self.ids.chip_box.children:
                if current_chip is not chip:
                    if chip.active:
                        chip.active = False


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = ChipScreen()

    def build(self) -> ChipScreen:
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "LightGreen"
        return self.screen

    def on_start(self) -> None:
        asynckivy.start(self.screen.create_chips())


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-filtering-single-select.gif

Input#

Input chips represent discrete pieces of information entered by a user, such as Gmail contacts or filter options within a search field.

They enable user input and verify that input by converting text into chips.

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

Example of input#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        type: "input"
        line_color: "grey"
        _no_ripple_effect: True

        MDChipLeadingAvatar:
            source: "data/logo/kivy-icon-128.png"

        MDChipText:
            text: "MDChip"

        MDChipTrailingIcon:
            icon: "close"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/example-input-chip.png

Suggestion#

Suggestion chips help narrow a user’s intent by presenting dynamically generated suggestions, such as possible responses or search filters.

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

Example of suggestion#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        type: "suggestion"
        line_color: "grey"

        MDChipText:
            text: "MDChip"
'''


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


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

API break#

1.1.1 version#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        text: "Portland"
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.on_release_chip(self)
'''


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

    def on_release_chip(self, instance_check):
        print(instance_check)


Test().run()

1.2.0 version#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        line_color: "grey"
        on_release: app.on_release_chip(self)

        MDChipText:
            text: "MDChip"
'''


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

    def on_release_chip(self, instance_check):
        print(instance_check)


Example().run()

API - kivymd.uix.chip.chip#

class kivymd.uix.chip.chip.MDChipLeadingAvatar(**kwargs)#

Implements the leading avatar for the chip.

For more information, see in the CircularRippleBehavior and ScaleBehavior and ButtonBehavior and MDIcon classes documentation.

class kivymd.uix.chip.chip.MDChipLeadingIcon(**kwargs)#

Implements the leading icon for the chip.

For more information, see in the CircularRippleBehavior and ScaleBehavior and ButtonBehavior and MDIcon classes documentation.

class kivymd.uix.chip.chip.MDChipTrailingIcon(**kwargs)#

Implements the trailing icon for the chip.

For more information, see in the CircularRippleBehavior and ScaleBehavior and ButtonBehavior and MDIcon classes documentation.

class kivymd.uix.chip.chip.MDChipText(*args, **kwargs)#

Implements the label for the chip.

For more information, see in the MDLabel classes documentation.

class kivymd.uix.chip.chip.MDChip(*args, **kwargs)#

Chip class.

For more information, see in the MDBoxLayout and RectangularRippleBehavior and ButtonBehavior and CommonElevationBehavior and TouchBehavior classes documentation.

radius#

Chip radius.

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

text#

Chip text.

Deprecated since version 1.2.0.

text is an StringProperty and defaults to ‘’.

type#

Type of chip.

New in version 1.2.0.

Available options are: ‘assist’, ‘filter’, ‘input’, ‘suggestion’.

type is an OptionProperty and defaults to ‘suggestion’.

icon_left#

Chip left icon.

New in version 1.0.0.

Deprecated since version 1.2.0.

icon_left is an StringProperty and defaults to ‘’.

icon_right#

Chip right icon.

New in version 1.0.0.

Deprecated since version 1.2.0.

icon_right is an StringProperty and defaults to ‘’.

text_color#

Chip’s text color in (r, g, b, a) or string format.

Deprecated since version 1.2.0.

text_color is an ColorProperty and defaults to None.

icon_right_color#

Chip’s right icon color in (r, g, b, a) or string format.

New in version 1.0.0.

Deprecated since version 1.2.0.

icon_right_color is an ColorProperty and defaults to None.

icon_left_color#

Chip’s left icon color in (r, g, b, a) or string format.

New in version 1.0.0.

Deprecated since version 1.2.0.

icon_left_color is an ColorProperty and defaults to None.

icon_check_color#

Chip’s check icon color in (r, g, b, a) or string format.

New in version 1.0.0.

icon_check_color is an ColorProperty and defaults to None.

active#

Whether the check is marked or not.

New in version 1.0.0.

active is an BooleanProperty and defaults to False.

selected_color#

The background color of the chip in the marked state in (r, g, b, a) or string format.

New in version 1.2.0.

selected_color is an ColorProperty and defaults to None.

on_long_touch(self, *args)#

Called when the widget is pressed for a long time.

on_type(self, instance, value: str)#

Called when the values of type change.

on_active(self, instance_check, active_value: bool)#

Called when the values of active change.

complete_anim_ripple(self, *args)#

Called at the end of the ripple animation.

remove_marked_icon_from_chip(self)#
add_marked_icon_to_chip(self)#

Adds and animates a check icon to the chip.

set_chip_bg_color(self, color: list | str)#

Animates the background color of the chip.

on_press(self, *args)#
add_widget(self, widget, *args, **kwargs)#

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)