Button#

#

Buttons allow users to take actions, and make choices, with a single tap. When choosing the right button for an action, consider the level of emphasis each button type provides.

KivyMD provides the following button classes for use:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/buttons.png
  1. Elevated button

  2. Filled button

  3. Filled tonal button

  4. Outlined button

  5. Text button

  6. Icon button

  7. Segmented button

  8. Floating action button (FAB)

  9. Extended FAB

Common buttons#

Buttons help people take action, such as sending an email, sharing a document, or liking a comment.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/common-buttons.png
  1. Elevated button

  2. Filled button

  3. Filled tonal button

  4. Outlined button

  5. Text button

Elevated Filled Tonal Outlined Text

Elevated#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.surfaceColor

    MDButton:
        style: "elevated"
        pos_hint: {"center_x": .5, "center_y": .5}

        MDButtonIcon:
            icon: "plus"

        MDButtonText:
            text: "Elevated"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/elevated-button.gif

Common buttons can contain an icon or be without an icon:

MDButton:
    style: "elevated"
    text: "Elevated"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/elevated-without-icon-button.png

Filled#

MDButton:
    style: "filled"

    MDButtonText:
        text: "Filled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/filled-button.gif

Tonal#

MDButton:
    style: "tonal"

    MDButtonText:
        text: "Tonal"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tonal-button.gif

Outlined#

MDButton:
    style: "outlined"

    MDButtonText:
        text: "Outlined"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/outlined-button.gif

Text#

MDButton:
    style: "text"

    MDButtonText:
        text: "Text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-button.gif

Customization of buttons#

Text positioning and button size#

MDButton:
    style: "tonal"
    theme_width: "Custom"
    height: "56dp"
    size_hint_x: .5

    MDButtonIcon:
        x: text.x - (self.width + dp(10))
        icon: "plus"

    MDButtonText:
        id: text
        text: "Tonal"
        pos_hint: {"center_x": .5, "center_y": .5}
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/positioning-size-button.png

Font of the button text#

MDButton:
    style: "filled"

    MDButtonIcon:
        icon: "plus"

    MDButtonText:
        text: "Filled"
        font_style: "Title"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/font-style-button-text.png
MDButton:
    style: "elevated"

    MDButtonText:
        text: "Elevated"
        theme_font_name: "Custom"
        font_name: "path/to/font.ttf"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/font-name-button-text.png

Custom button color#

MDButton:
    style: "elevated"
    theme_shadow_color: "Custom"
    shadow_color: "red"

    MDButtonIcon:
        icon: "plus"
        theme_icon_color: "Custom"
        icon_color: "green"

    MDButtonText:
        text: "Elevated"
        theme_text_color: "Custom"
        text_color: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/custom-color-button.png

Icon buttons#

Use icon buttons when a compact button is required, such as in a toolbar or image list. There are two types of icon buttons: standard and contained.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-buttons.png
  1. Standard icon button

  2. Contained icon button (including filled, filled tonal, and outlined styles)

StandardIcon FilledIcon TonalIcon OutlinedIcon

StandardIcon#

MDIconButton:
    icon: "heart-outline"
    style: "standard"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-standard.gif

FilledIcon#

MDIconButton:
    icon: "heart-outline"
    style: "filled"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-filled.gif

TonalIcon#

MDIconButton:
    icon: "heart-outline"
    style: "tonal"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-tonal.gif

OutlinedIcon#

MDIconButton:
    icon: "heart-outline"
    style: "outlined"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-outlined.gif

Custom icon size#

MDIconButton:
    icon: "heart-outline"
    style: "tonal"
    theme_font_size: "Custom"
    font_size: "48sp"
    radius: [self.height / 2, ]
    size_hint: None, None
    size: "84dp", "84dp"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-size.png

Custom button color#

MDIconButton:
    icon: "heart-outline"
    style: "tonal"
    theme_bg_color: "Custom"
    md_bg_color: "brown"
    theme_icon_color: "Custom"
    icon_color: "white"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-button-color.png

FAB buttons#

The FAB represents the most important action on a screen. It puts key actions within reach.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-buttons.png
  1. Standard FAB

  2. Small FAB

  3. Large FAB

There are three sizes of floating action buttons: FAB, small FAB, and large FAB:

Standard Small Large

Standard#

MDFabButton:
    icon: "pencil-outline"
    style: "standard"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-button-standard.gif

Small#

MDFabButton:
    icon: "pencil-outline"
    style: "small"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-button-small.png

Large#

MDFabButton:
    icon: "pencil-outline"
    style: "large"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-button-large.gif

Additional color mappings#

FABs can use other combinations of container and icon colors. The color mappings below provide the same legibility and functionality as the default, so the color mapping you use depends on style alone.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-color-mapping.png
  1. Surface

  2. Secondary

  3. Tertiary

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.button import MDFabButton

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.surfaceColor

    MDBoxLayout:
        id: box
        adaptive_size: True
        spacing: "32dp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


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

    def on_start(self):
        super().on_start()
        styles = {
            "standard": "surface",
            "small": "secondary",
            "large": "tertiary",
        }
        for style in styles.keys():
            self.root.ids.box.add_widget(
                MDFabButton(
                    style=style, icon="pencil-outline", color_map=styles[style]
                )
            )


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fab-button-color-mapping.png

Extended FAB#

Extended floating action buttons (extended FABs) help people take primary actions. They’re wider than FABs to accommodate a text label and larger target area.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/extended-fab-button.png
  1. Extended FAB with both icon and label text

  2. Extended FAB without icon

With icon#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.surfaceColor
    on_touch_down:
        if not btn.collide_point(*args[1].pos): \
        btn.fab_state = "expand" \
        if btn.fab_state == "collapse" else "collapse"

        MDExtendedFabButton:
            id: btn
            pos_hint: {"center_x": .5, "center_y": .5}

            MDExtendedFabButtonIcon:
                icon: "pencil-outline"

            MDExtendedFabButtonText:
                text: "Compose"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/extended-fab-button-icon.gif

Without icon#

MDExtendedFabButton:
    fab_state: "expand"

    MDExtendedFabButtonText:
        text: "Compose"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/extended-fab-button-without-icon.png

API break#

1.2.0 version#

MDFloatingActionButton:
    icon: "plus"
MDRoundFlatButton:
    text: "Outlined"
MDRoundFlatIconButton:
    text: "Outlined with icon"
    icon: "plus"
MDFillRoundFlatButton
    text: "Filled"
MDFillRoundFlatIconButton
    text: "Filled with icon"
    icon: "plus"

2.0.0 version#

Note

MDFloatingActionButtonSpeedDial type buttons were removed in version 2.0.0.

MDFabButton:
    icon: "plus"
MDButton:
    style: "outlined"

    MDButtonText:
        text: "Outlined"
MDButton:
    style: "outlined"

    MDButtonIcon:
        icon: "plus"

    MDButtonText:
        text: "Outlined with icon"
MDButton:
    style: "filled"

    MDButtonText:
        text: "Filled"
MDButton:
    style: "filled"

    MDButtonIcon:
        icon: "plus"

    MDButtonText:
        text: "Filled"

API - kivymd.uix.button.button#

class kivymd.uix.button.button.BaseFabButton#

Implements the basic properties for the MDExtendedFabButton and MDFabButton classes.

New in version 2.0.0.

elevation_levels#

Elevation is measured as the distance between components along the z-axis in density-independent pixels (dps).

New in version 1.2.0.

elevation_levels is an DictProperty and defaults to {0: dp(0), 1: dp(4), 2: dp(8), 3: dp(12), 4: dp(16), 5: dp(18)}.

color_map#

Additional color mappings.

Available options are: ‘surface’, ‘secondary’, ‘tertiary’.

color_map is an OptionProperty and defaults to ‘secondary’.

icon_color_disabled#

The icon color in (r, g, b, a) or string format of the list item when the widget item is disabled.

icon_color_disabled is a ColorProperty and defaults to None.

style#

Button type.

Available options are: ‘standard’, ‘small’, ‘large’.

style is an OptionProperty and defaults to ‘standard’.

fab_state#

The state of the button.

Available options are: ‘collapse’ or ‘expand’.

fab_state is an OptionProperty and defaults to “collapse”.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

radius#

Canvas radius.

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

class kivymd.uix.button.button.BaseButton(*args, **kwargs)#

Base button class.

For more information, see in the DeclarativeBehavior and BackgroundColorBehavior and RectangularRippleBehavior and ButtonBehavior and ThemableBehavior and StateLayerBehavior classes documentation.

elevation_levels#

Elevation is measured as the distance between components along the z-axis in density-independent pixels (dps).

New in version 1.2.0.

elevation_levels is an DictProperty and defaults to {0: dp(0), 1: dp(4), 2: dp(8), 3: dp(12), 4: dp(16), 5: dp(18)}.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

shadow_radius#

Button shadow radius.

shadow_radius is an VariableListProperty and defaults to [0, 0, 0, 0].

md_bg_color#

Button background color in (r, g, b, a) or string format.

md_bg_color is a ColorProperty and defaults to None.

line_color#

Outlined color.

line_color is a ColorProperty and defaults to None.

line_width#

Line width for button border.

line_width is a NumericProperty and defaults to 1.

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

class kivymd.uix.button.button.MDButton(*args, **kwargs)#

Base class for all buttons.

New in version 2.2.0.

For more information, see in the CommonElevationBehavior and BaseButton and RelativeLayout classes documentation.

style#

Button type.

Available options are: ‘filled’, ‘elevated’, ‘outlined’, ‘tonal’, ‘text’.

style is an OptionProperty and defaults to ‘elevated’.

radius#

Button radius.

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

adjust_pos(*args) None#

Adjusts the pos of the button according to the content.

adjust_width(*args) None#

Adjusts the width of the button according to the content.

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.

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)
set_properties_widget() None#

Fired on_release/on_press/on_enter/on_leave events.

class kivymd.uix.button.button.MDButtonText(*args, **kwargs)#

The class implements the text for the MDButton class.

For more information, see in the MDLabel class documentation.

class kivymd.uix.button.button.MDButtonIcon(*args, **kwargs)#

The class implements an icon for the MDButton class.

For more information, see in the MDIcon class documentation.

class kivymd.uix.button.button.MDIconButton(**kwargs)#

Base class for icon buttons.

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

style#

Button type.

New in version 2.0.0.

Available options are: ‘standard’, ‘filled’, ‘tonal’, ‘outlined’.

style is an OptionProperty and defaults to ‘standard’.

md_bg_color_disabled#

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

md_bg_color_disabled is a ColorProperty and defaults to None.

on_line_color(instance, value) None#

Fired when the values of line_color change.

class kivymd.uix.button.button.MDFabButton(**kwargs)#

Base class for FAB buttons.

For more information, see in the BaseFabButton and CommonElevationBehavior and RectangularRippleBehavior and ButtonBehavior and MDIcon classes documentation.

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

set_properties_widget() None#

Fired on_release/on_press/on_enter/on_leave events.

class kivymd.uix.button.button.MDExtendedFabButtonIcon(*args, **kwargs)#

Implements an icon for the MDExtendedFabButton class.

New in version 2.0.0.

class kivymd.uix.button.button.MDExtendedFabButtonText(*args, **kwargs)#

Implements the text for the class MDExtendedFabButton class.

New in version 2.0.0.

class kivymd.uix.button.button.MDExtendedFabButton(*args, **kwargs)#

Base class for Extended FAB buttons.

New in version 2.0.0.

For more information, see in the DeclarativeBehavior and ThemableBehavior and MotionExtendedFabButtonBehavior and CommonElevationBehavior and StateLayerBehavior and BaseFabButton and ButtonBehavior and RelativeLayout classes documentation.

Events:
on_collapse

Fired when the button is collapsed.

on_expand

Fired when the button is expanded.

elevation_levels#

Elevation is measured as the distance between components along the z-axis in density-independent pixels (dps).

New in version 1.2.0.

elevation_levels is an DictProperty and defaults to {0: dp(0), 1: dp(4), 2: dp(8), 3: dp(12), 4: dp(16), 5: dp(18)}.

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.

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)
on_collapse(*args)#

Fired when the button is collapsed.

on_expand(*args)#

Fired when the button is expanded.

on_fab_state(instance, state: str) None#

Fired when the fab_state value changes.

on__x(instance, value) None#