SelectionControls

See also

Material Design spec, Checkbox

Material Design spec, Switch

Selection controls allow the user to select options.

KivyMD provides the following selection controls classes for use:

• MDCheckbox

• MDSwitch

MDCheckbox

Usage

from kivy.lang import Builder

from kivymd.app import MDApp


KV = '''
MDFloatLayout:

    MDCheckbox:
        size_hint: None, None
        size: "48dp", "48dp"
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


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


Example().run()

Note

Be sure to specify the size of the checkbox. By default, it is (dp(48), dp(48)), but the ripple effect takes up all the available space.

Control state

MDCheckbox:
    on_active: app.on_checkbox_active(*args)

def on_checkbox_active(self, checkbox, value):
    if value:
        print('The checkbox', checkbox, 'is active', 'and', checkbox.state, 'state')
    else:
        print('The checkbox', checkbox, 'is inactive', 'and', checkbox.state, 'state')

MDCheckbox with group

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<Check@MDCheckbox>:
    group: 'group'
    size_hint: None, None
    size: dp(48), dp(48)


MDFloatLayout:

    Check:
        active: True
        pos_hint: {'center_x': .4, 'center_y': .5}

    Check:
        pos_hint: {'center_x': .6, 'center_y': .5}
'''


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


Example().run()

Parent and child checkboxes

Checkboxes can have a parent-child relationship with other checkboxes. When the parent checkbox is checked, all child checkboxes are checked. If a parent checkbox is unchecked, all child checkboxes are unchecked. If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox.

Usage

MDCheckbox:
    group: "root"  # this is a required name for the parent checkbox group

MDCheckbox:
    group: "child"  # this is a required name for a group of child checkboxes

MDCheckbox:
    group: "child"  # this is a required name for a group of child checkboxes

Example

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

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout

KV = '''
<CheckItem>
    adaptive_height: True

    MDCheckbox:
        size_hint: None, None
        size: "48dp", "48dp"
        group: root.group

    MDLabel:
        text: root.text
        adaptive_height: True
        theme_text_color: "Custom"
        text_color: "#B2B6AE"
        pos_hint: {"center_y": .5}


MDBoxLayout:
    orientation: "vertical"
    md_bg_color: "#141612"

    MDTopAppBar:
        md_bg_color: "#21271F"
        specific_text_color: "#B2B6AE"
        elevation: 0
        title: "Meal options"
        left_action_items: [["arrow-left", lambda x: x]]
        anchor_title: "left"

    MDBoxLayout:
        orientation: "vertical"
        adaptive_height: True
        padding: "12dp", "36dp", 0, 0

        CheckItem:
            text: "Recieve emails"
            group: "root"

        MDBoxLayout:
            orientation: "vertical"
            adaptive_height: True
            padding: "24dp", 0, 0, 0

            CheckItem:
                text: "Daily"
                group: "child"

            CheckItem:
                text: "Weekly"
                group: "child"

            CheckItem:
                text: "Monthly"
                group: "child"

    MDWidget:
'''


class CheckItem(MDBoxLayout):
    text = StringProperty()
    group = StringProperty()


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


Example().run()

MDSwitch

Usage

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDFloatLayout:

    MDSwitch:
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


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


Example().run()

Note

Control state of MDSwitch same way as in MDCheckbox.

API - kivymd.uix.selectioncontrol.selectioncontrol

class kivymd.uix.selectioncontrol.selectioncontrol.MDCheckbox(**kwargs)

Checkbox class.

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

active

Indicates if the checkbox is active or inactive.

active is a BooleanProperty and defaults to False.

checkbox_icon_normal

Background icon of the checkbox used for the default graphical representation when the checkbox is not pressed.

checkbox_icon_normal is a StringProperty and defaults to ‘checkbox-blank-outline’.

checkbox_icon_down

Background icon of the checkbox used for the default graphical representation when the checkbox is pressed.

checkbox_icon_down is a StringProperty and defaults to ‘checkbox-marked’.

radio_icon_normal

Background icon (when using the group option) of the checkbox used for the default graphical representation when the checkbox is not pressed.

radio_icon_normal is a StringProperty and defaults to ‘checkbox-blank-circle-outline’.

radio_icon_down

Background icon (when using the group option) of the checkbox used for the default graphical representation when the checkbox is pressed.

radio_icon_down is a StringProperty and defaults to ‘checkbox-marked-circle’.

color_active

Color in (r, g, b, a) or string format when the checkbox is in the active state.

New in version 1.0.0.

MDCheckbox:
    color_active: "red"

color_active is a ColorProperty and defaults to None.

color_inactive

Color in (r, g, b, a) or string format when the checkbox is in the inactive state.

New in version 1.0.0.

MDCheckbox:
    color_inactive: "blue"

color_inactive is a ColorProperty and defaults to None.

disabled_color

Color in (r, g, b, a) or string format when the checkbox is in the disabled state.

MDCheckbox:
    disabled_color: "lightgrey"
    disabled: True
    active: True

disabled_color is a ColorProperty and defaults to None.

selected_color

Color in (r, g, b, a) or string format when the checkbox is in the active state.

Deprecated since version 1.0.0: Use color_active instead.

selected_color is a ColorProperty and defaults to None.

unselected_color

Color in (r, g, b, a) or string format when the checkbox is in the inactive state.

Deprecated since version 1.0.0: Use color_inactive instead.

unselected_color is a ColorProperty and defaults to None.

update_primary_color(self, instance, value)

Called when the values of kivymd.theming.ThemableBehavior.theme_cls.theme_style and kivymd.theming.ThemableBehavior.theme_cls.primary_color change.

update_icon(self, *args)

Called when the values of checkbox_icon_normal and checkbox_icon_down and radio_icon_normal and group change.

update_color(self, *args)

Called when the values of color_active and color_inactive and disabled_color and disabled and state change.

on_state(self, *args)

Called when the values of state change.

on_active(self, *args)

Called when the values of active change.

set_root_active(self)

set_child_active(self, active: bool)

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.

class kivymd.uix.selectioncontrol.selectioncontrol.MDSwitch(**kwargs)

Switch class.

For more information, see in the ThemableBehavior and FloatLayout classes documentation.

active

Indicates if the switch is active or inactive.

active is a BooleanProperty and defaults to False.

icon_active

Thumb icon when the switch is in the active state (only M3 style).

New in version 1.0.0.

MDSwitch:
    active: True
    icon_active: "check"

icon_active is a StringProperty and defaults to ‘’.

icon_inactive

Thumb icon when the switch is in an inactive state (only M3 style).

New in version 1.0.0.

MDSwitch:
    icon_inactive: "close"

icon_inactive is a StringProperty and defaults to ‘’.

icon_active_color

Thumb icon color in (r, g, b, a) or string format when the switch is in the active state (only M3 style).

New in version 1.0.0.

MDSwitch:
    active: True
    icon_active: "check"
    icon_active_color: "white"

icon_active_color is a ColorProperty and defaults to None.

icon_inactive_color

Thumb icon color in (r, g, b, a) or string format when the switch is in an inactive state (only M3 style).

New in version 1.0.0.

MDSwitch:
    icon_inactive: "close"
    icon_inactive_color: "grey"

icon_inactive_color is a ColorProperty and defaults to None.

thumb_color_active

The color in (r, g, b, a) or string format of the thumb when the switch is active.

New in version 1.0.0.

MDSwitch:
    active: True
    thumb_color_active: "brown"

thumb_color_active is an ColorProperty and default to None.

thumb_color_inactive

The color in (r, g, b, a) or string format of the thumb when the switch is inactive.

New in version 1.0.0.

MDSwitch:
    thumb_color_inactive: "brown"

thumb_color_inactive is an ColorProperty and default to None.

thumb_color_disabled

The color in (r, g, b, a) or string format of the thumb when the switch is in the disabled state.

MDSwitch:
    active: True
    thumb_color_disabled: "brown"
    disabled: True

thumb_color_disabled is an ColorProperty and default to None.

track_color_active

The color in (r, g, b, a) or string format of the track when the switch is active.

MDSwitch:
    active: True
    track_color_active: "red"

track_color_active is an ColorProperty and default to None.

track_color_inactive

The color in (r, g, b, a) or string format of the track when the switch is inactive.

New in version 1.0.0.

MDSwitch:
    track_color_inactive: "red"

track_color_inactive is an ColorProperty and default to None.

track_color_disabled

The color in (r, g, b, a) or string format of the track when the switch is in the disabled state.

MDSwitch:
    track_color_disabled: "lightgrey"
    disabled: True

track_color_disabled is an ColorProperty and default to None.

set_icon(self, instance_switch, icon_value: str)

Called when the values of icon_active and icon_inactive change.

on_active(self, instance_switch, active_value: bool)

Called when the values of active change.

on_thumb_down(self)

Called at the on_touch_down event of the Thumb object. Indicates the state of the switch “on/off” by an animation of increasing the size of the thumb.