Chip#
See also 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. Container Label text Leading icon or image (optional) Trailing remove icon (optional, input & filter chips only) All chips are slightly rounded with an 8dp corner. Chip containers can be elevated if the placement requires protection, such as
on top of an image. 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. 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. Tap a chip to select it. Multiple chips can be selected or unselected: Alternatively, a single chip can be selected.
This offers an alternative to toggle buttons, radio buttons, or single select
menus: 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. Suggestion chips
help narrow a user’s intent by presenting dynamically generated suggestions,
such as possible responses or search filters.
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()
from kivymd.app import MDApp
from kivymd.uix.chip import MDChip, MDChipText
from kivymd.uix.screen import MDScreen
class Example(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
return (
MDScreen(
MDChip(
MDChipText(
text="MDChip"
),
pos_hint={"center_x": .5, "center_y": .5},
)
)
)
Example().run()
Anatomy#
Container#
Shadows and elevation#
The following types of chips are available:#
Assist#
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()
Filter#
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()
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()
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()
Input#
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()
Suggestion#
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()
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
andScaleBehavior
andButtonBehavior
andMDIcon
classes documentation.
- class kivymd.uix.chip.chip.MDChipLeadingIcon(**kwargs)#
Implements the leading icon for the chip.
For more information, see in the
CircularRippleBehavior
andScaleBehavior
andButtonBehavior
andMDIcon
classes documentation.
- class kivymd.uix.chip.chip.MDChipTrailingIcon(**kwargs)#
Implements the trailing icon for the chip.
For more information, see in the
CircularRippleBehavior
andScaleBehavior
andButtonBehavior
andMDIcon
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
andRectangularRippleBehavior
andButtonBehavior
andCommonElevationBehavior
andTouchBehavior
classes documentation.- radius#
Chip radius.
radius
is anVariableListProperty
and defaults to [dp(8), dp(8), dp(8), dp(8)].
- text#
Chip text.
Deprecated since version 1.2.0.
text
is anStringProperty
and defaults to ‘’.
- type#
Type of chip.
New in version 1.2.0.
Available options are: ‘assist’, ‘filter’, ‘input’, ‘suggestion’.
type
is anOptionProperty
and defaults to ‘suggestion’.
- icon_left#
Chip left icon.
New in version 1.0.0.
Deprecated since version 1.2.0.
icon_left
is anStringProperty
and defaults to ‘’.
- icon_right#
Chip right icon.
New in version 1.0.0.
Deprecated since version 1.2.0.
icon_right
is anStringProperty
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 anColorProperty
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 anColorProperty
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 anColorProperty
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 anColorProperty
and defaults to None.
- active#
Whether the check is marked or not.
New in version 1.0.0.
active
is anBooleanProperty
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 anColorProperty
and defaults to None.
- on_long_touch(self, *args)#
Called when the widget is pressed for a long time.
- 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.
- 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.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)