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

Declarative KV styleDeclarative Python style

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

Declarative KV styleDeclarative Python style

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

Declarative KV styleDeclarative Python style

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

Declarative KV styleDeclarative Python style

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

Declarative KV styleDeclarative Python style

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:
        group: root.group

    MDLabel:
        text: root.text
        adaptive_height: True
        padding_x: "12dp"
        pos_hint: {"center_y": .5}


MDBoxLayout:
    orientation: "vertical"
    md_bg_color: self.theme_cls.backgroundColor

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

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

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

            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.primary_palette = "Teal"
        return Builder.load_string(KV)


Example().run()

MDSwitch

Usage

Declarative KV styleDeclarative Python style

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 StateLayerBehavior and CircularRippleBehavior and ScaleBehavior and ToggleButtonBehavior and MDIcon classes documentation.

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.

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

Added in version 1.0.0.

MDCheckbox:
    color_inactive: "blue"

color_inactive is a ColorProperty and defaults to None.

color_disabled

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

Added in version 2.0.0: Use color_disabled instead.

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

Deprecated since version 2.0.0: Use color_disabled instead.

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_icon(*args) → None

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

set_root_active() → None

set_child_active(active: bool)

on_state(*args) → None

Fired when the values of state change.

on_active(*args) → None

Fired when the values of active change.

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.

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

Switch class.

For more information, see in the StateLayerBehavior and ButtonBehavior and MDFloatLayout classes documentation.

width

height

md_bg_color_disabled

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

md_bg_color_disabled is a ColorProperty and defaults to None.

ripple_effect

Allows or does not allow the ripple effect when activating/deactivating the switch.

Added in version 2.0.0.

ripple_effect is a BooleanProperty and defaults to True.

icon_active

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

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

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

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

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

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

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

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

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.

set_icon(instance_switch, icon_value: str) → None

Fired when the values of icon_active and icon_inactive change.

on_line_color(instance, value) → None

Fired when the values of line_color change.

on_active(*args) → None

Fired when the values of active change.

on_thumb_down() → None

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