Chip

See also

Material Design 3 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.

Usage

Declarative KV styleDeclarative Python style

MDChip:

    MDChipLeadingAvatar:  # MDChipLeadingIcon

    MDChipText:

    MDChipTrailingIcon:

Anatomy

Example

Declarative KV styleDeclarative Python style

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

The following types of chips are available:

• Assist

• Filter

• Input

• Suggestion

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.

Example of assist

Imperative python style with KVDeclarative python style

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"
    theme_bg_color: "Custom"
    md_bg_color: "#2a3127"
    theme_line_color: "Custom"
    line_color: "grey"
    theme_elevation_level: "Custom"
    elevation_level: 1
    theme_shadow_softness: "Custom"
    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: "Display"
            role: "large"
            padding_y: "12dp"

        CommonLabel:
            text: "Video call"
            font_style: "Display"
            role: "small"
            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()

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.

Example of filtering

Imperative python style with KVDeclarative python style

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 MDListItem
from kivymd.icon_definitions import md_icons
from kivymd.uix.screen import MDScreen

import asynckivy

Builder.load_string(
    '''
<CustomOneLineIconListItem>

    MDListItemLeadingIcon:
        icon: root.icon

    MDListItemHeadlineText:
        text: root.text


<PreviewIconsScreen>

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

        MDTextField:
            id: search_field
            mode: "outlined"
            on_text: root.set_list_md_icons(self.text, True)

            MDTextFieldLeadingIcon:
                icon: "magnify"

            MDTextFieldHintText:
                text: "Search icon"

        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(MDListItem):
    icon = StringProperty()
    text = 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",
                    selected_color="green",
                    theme_bg_color="Custom",
                    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"
        return self.screen

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


Example().run()

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

Imperative python style with KVDeclarative python style

from kivy.lang import Builder

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

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:

    MDButton:
        pos: "20dp", "20dp"
        on_release: root.unchecks_chips()

        MDButtonText:
            text: "Uncheck 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",
                    selected_color="green",
                    theme_bg_color="Custom",
                    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"
        return self.screen

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


Example().run()

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

Imperative python style with KVDeclarative python style

from kivy.lang import Builder

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

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:
    '''
)


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",
                selected_color="green",
                theme_bg_color="Custom",
                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()

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.

Example of input

Imperative python style with KVDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        type: "input"
        theme_line_color: "Custom"
        line_color: "grey"
        ripple_effect: False

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

Suggestion

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

Example of suggestion

Imperative python style with KVDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        type: "suggestion"
        theme_line_color: "Custom"
        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()

API break

1.2.0 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()

2.0.0 version

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDChip:
        pos_hint: {"center_x": .5, "center_y": .5}
        theme_line_color: "Custom"
        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.

text_color_disabled

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

Added in version 2.0.0.

text_color_disabled is a ColorProperty and defaults to None.

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)].

type

Type of chip.

Added in version 2.0.0.

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

type is an OptionProperty and defaults to ‘suggestion’.

active

Whether the check is marked or not.

Added 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.

Added in version 2.0.0.

selected_color is an ColorProperty and defaults to None.

line_color_disabled

The color of the outline in the disabled state

Added in version 2.0.0.

line_color_disabled is an ColorProperty and defaults to None.

on_long_touch(*args) → None

Fired when the widget is pressed for a long time.

on_line_color(instance, value) → None

Fired when the values of line_color change.

on_type(instance, value: str) → None

Fired when the values of type change.

on_active(instance_check, active_value: bool) → None

Called when the values of active change.

complete_anim_ripple(*args) → None

Called at the end of the ripple animation.

remove_marked_icon_from_chip() → None

add_marked_icon_to_chip() → None

Adds and animates a check icon to the chip.

set_chip_bg_color(color: list | str) → None

Animates the background color of the chip.

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

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

Added 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.

Added 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)