Button

See also

Material Design spec, Buttons

Material Design spec, Buttons: floating action button

Buttons allow users to take actions, and make choices, with a single tap.

KivyMD provides the following button classes for use:

• MDIconButton

• MDFloatingActionButton

• MDFlatButton

• MDRaisedButton

• MDRectangleFlatButton

• MDRectangleFlatIconButton

• MDRoundFlatButton

• MDRoundFlatIconButton

• MDFillRoundFlatButton

• MDFillRoundFlatIconButton

• MDTextButton

• MDFloatingActionButtonSpeedDial

MDIconButton

Declarative KV styleDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDIconButton:
        icon: "language-python"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


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


Example().run()

The icon parameter must have the name of the icon from kivymd/icon_definitions.py file.

You can also use custom icons:

MDIconButton:
    icon: "kivymd/images/logo/kivymd-icon-256.png"

By default, MDIconButton button has a size (dp(48), dp (48)). Use icon_size attribute to resize the button:

MDIconButton:
    icon: "android"
    icon_size: "64sp"

By default, the color of MDIconButton (depending on the style of the application) is black or white. You can change the color of MDIconButton as the text color of MDLabel, substituting theme_icon_color for theme_text_color and icon_color for text_color.

MDIconButton:
    icon: "android"
    theme_icon_color: "Custom"
    icon_color: app.theme_cls.primary_color

MDFloatingActionButton

The above parameters for MDIconButton apply to MDFloatingActionButton.

To change MDFloatingActionButton background, use the md_bg_color parameter:

MDFloatingActionButton:
    icon: "android"
    md_bg_color: app.theme_cls.primary_color

Material design style 3

from kivy.lang import Builder

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

KV = '''
MDScreen:
    md_bg_color: "#f7f2fa"

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


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

    def on_start(self):
        data = {
            "standard": {"md_bg_color": "#fefbff", "text_color": "#6851a5"},
            "small": {"md_bg_color": "#e9dff7", "text_color": "#211c29"},
            "large": {"md_bg_color": "#f8d7e3", "text_color": "#311021"},
        }
        for type_button in data.keys():
            self.root.ids.box.add_widget(
                MDFloatingActionButton(
                    icon="pencil",
                    type=type_button,
                    theme_icon_color="Custom",
                    md_bg_color=data[type_button]["md_bg_color"],
                    icon_color=data[type_button]["text_color"],
                )
            )


Example().run()

MDFlatButton

To change the text color of: class:~MDFlatButton use the text_color parameter:

MDFlatButton:
    text: "MDFlatButton"
    theme_text_color: "Custom"
    text_color: "orange"

Or use markup:

MDFlatButton:
    text: "[color=#00ffcc]MDFlatButton[/color]"

To specify the font size and font name, use the parameters as in the usual Kivy buttons:

MDFlatButton:
    text: "MDFlatButton"
    font_size: "18sp"
    font_name: "path/to/font"

MDRaisedButton

This button is similar to the MDFlatButton button except that you can set the background color for MDRaisedButton:

MDRaisedButton:
    text: "MDRaisedButton"
    md_bg_color: "red"

MDRectangleFlatButton

MDRectangleFlatButton:
    text: "MDRectangleFlatButton"
    theme_text_color: "Custom"
    text_color: "white"
    line_color: "red"

MDRectangleFlatIconButton

Button parameters MDRectangleFlatIconButton are the same as button MDRectangleFlatButton, with the addition of the theme_icon_color and icon_color parameters as for MDIconButton.

MDRectangleFlatIconButton:
    icon: "android"
    text: "MDRectangleFlatIconButton"
    theme_text_color: "Custom"
    text_color: "white"
    line_color: "red"
    theme_icon_color: "Custom"
    icon_color: "orange"

Without border

from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen
from kivymd.uix.button import MDRectangleFlatIconButton


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        return (
            MDScreen(
                MDRectangleFlatIconButton(
                    text="MDRectangleFlatIconButton",
                    icon="language-python",
                    line_color=(0, 0, 0, 0),
                    pos_hint={"center_x": .5, "center_y": .5},
                )
            )
        )


Example().run()

MDRectangleFlatIconButton:
    text: "MDRectangleFlatIconButton"
    icon: "language-python"
    line_color: 0, 0, 0, 0
    pos_hint: {"center_x": .5, "center_y": .5}

MDRoundFlatButton

MDRoundFlatButton:
    text: "MDRoundFlatButton"
    text_color: "white"

MDRoundFlatIconButton

Button parameters MDRoundFlatIconButton are the same as button MDRoundFlatButton, with the addition of the theme_icon_color and icon_color parameters as for MDIconButton:

MDRoundFlatIconButton:
    text: "MDRoundFlatIconButton"
    icon: "android"
    text_color: "white"

MDFillRoundFlatButton

Button parameters MDFillRoundFlatButton are the same as button MDRaisedButton.

MDFillRoundFlatIconButton

Button parameters MDFillRoundFlatIconButton are the same as button MDRaisedButton, with the addition of the theme_icon_color and icon_color parameters as for MDIconButton.

Note

Notice that the width of the MDFillRoundFlatIconButton button matches the size of the button text.

MDTextButton

MDTextButton:
    text: "MDTextButton"
    custom_color: "white"

MDFloatingActionButtonSpeedDial

Note

See the full list of arguments in the class MDFloatingActionButtonSpeedDial.

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDFloatingActionButtonSpeedDial:
        data: app.data
        root_button_anim: True
'''


class Example(MDApp):
    data = {
        'Python': 'language-python',
        'PHP': 'language-php',
        'C++': 'language-cpp',
    }

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        return Builder.load_string(KV)


Example().run()

Or without KV Language:

Imperative python styleDeclarative python style

from kivymd.uix.screen import MDScreen
from kivymd.app import MDApp
from kivymd.uix.button import MDFloatingActionButtonSpeedDial


class Example(MDApp):
    data = {
        'Python': 'language-python',
        'PHP': 'language-php',
        'C++': 'language-cpp',
    }

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        screen = MDScreen()
        speed_dial = MDFloatingActionButtonSpeedDial()
        speed_dial.data = self.data
        speed_dial.root_button_anim = True
        screen.add_widget(speed_dial)
        return screen


Example().run()

You can use various types of animation of labels for buttons on the stack:

MDFloatingActionButtonSpeedDial:
    hint_animation: True

You can set your color values for background, text of buttons etc:

MDFloatingActionButtonSpeedDial:
    hint_animation: True
    bg_hint_color: app.theme_cls.primary_dark

Binds to individual buttons

Declarative KV styleDeclarative python style

from kivy.lang import Builder
from kivy.properties import DictProperty

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDFloatingActionButtonSpeedDial:
        id: speed_dial
        data: app.data
        root_button_anim: True
        hint_animation: True
'''


class Example(MDApp):
    data = DictProperty()

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        self.data = {
            'Python': 'language-python',
            'JS': [
                'language-javascript',
                "on_press", lambda x: print("pressed JS"),
                "on_release", lambda x: print(
                    "stack_buttons",
                    self.root.ids.speed_dial.stack_buttons
                )
            ],
            'PHP': [
                'language-php',
                "on_press", lambda x: print("pressed PHP"),
                "on_release", self.callback
            ],
            'C++': [
                'language-cpp',
                "on_press", lambda x: print("pressed C++"),
                "on_release", lambda x: self.callback()
            ],
        }
        return Builder.load_string(KV)

    def callback(self, *args):
        print(args)


Example().run()

API - kivymd.uix.button.button

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

Base class for all buttons.

For more information, see in the AnchorLayout class documentation.

padding

Padding between the widget box and its children, in pixels: [padding_left, padding_top, padding_right, padding_bottom].

padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].

New in version 1.0.0.

padding is a VariableListProperty and defaults to [16dp, 8dp, 16dp, 8dp].

halign

Horizontal anchor.

New in version 1.0.0.

anchor_x is an OptionProperty and defaults to ‘center’. It accepts values of ‘left’, ‘center’ or ‘right’.

valign

Vertical anchor.

New in version 1.0.0.

anchor_y is an OptionProperty and defaults to ‘center’. It accepts values of ‘top’, ‘center’ or ‘bottom’.

text

Button text.

text is a StringProperty and defaults to ‘’.

icon

Button icon.

icon is a StringProperty and defaults to ‘’.

font_style

Button text font style.

Available vanilla font_style are: ‘H1’, ‘H2’, ‘H3’, ‘H4’, ‘H5’, ‘H6’, ‘Subtitle1’, ‘Subtitle2’, ‘Body1’, ‘Body2’, ‘Button’, ‘Caption’, ‘Overline’, ‘Icon’.

font_style is a StringProperty and defaults to ‘Body1’.

theme_text_color

Button text type. Available options are: (“Primary”, “Secondary”, “Hint”, “Error”, “Custom”, “ContrastParentBackground”).

theme_text_color is an OptionProperty and defaults to None (set by button class).

theme_icon_color

Button icon type. Available options are: (“Primary”, “Secondary”, “Hint”, “Error”, “Custom”, “ContrastParentBackground”).

New in version 1.0.0.

theme_icon_color is an OptionProperty and defaults to None (set by button subclass).

text_color

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

text_color is a ColorProperty and defaults to None.

icon_color

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

icon_color is a ColorProperty and defaults to None.

font_name

Button text font name.

font_name is a StringProperty and defaults to ‘’.

font_size

Button text font size.

font_size is a NumericProperty and defaults to 14sp.

icon_size

Icon font size. Use this parameter as the font size, that is, in sp units.

New in version 1.0.0.

icon_size is a NumericProperty and defaults to None.

line_width

Line width for button border.

line_width is a NumericProperty and defaults to 1.

line_color

Line color in (r, g, b, a) or string format for button border.

line_color is a ColorProperty and defaults to None.

line_color_disabled

Disabled line color in (r, g, b, a) or string format for button border.

New in version 1.0.0.

line_color_disabled is a ColorProperty and defaults to None.

md_bg_color

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

md_bg_color is a ColorProperty and defaults to None.

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.

disabled_color

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

New in version 1.0.0.

disabled_color is a ColorProperty and defaults to None.

rounded_button

Should the button have fully rounded corners (e.g. like M3 buttons)?

New in version 1.0.0.

rounded_button is a BooleanProperty and defaults to False.

set_disabled_color(self, *args)

Sets the color for the icon, text and line of the button when button is disabled.

set_all_colors(self, *args)

Set all button colours.

set_button_colors(self, *args)

Set all button colours (except text/icons).

set_text_color(self, *args)

Set _theme_text_color and _text_color based on defaults and options.

set_icon_color(self, *args)

Set _theme_icon_color and _icon_color based on defaults and options.

set_radius(self, *args)

Set the radius, if we are a rounded button, based on the current height.

on_touch_down(self, touch)

Animates fade to background on press, for buttons with no background color.

on_touch_up(self, touch)

Animates return to original background on touch release.

on_disabled(self, instance_button, disabled_value: bool)

class kivymd.uix.button.button.MDFlatButton(*args, **kwargs)

A flat rectangular button with (by default) no border or background. Text is the default text color.

padding

Padding between the widget box and its children, in pixels: [padding_left, padding_top, padding_right, padding_bottom].

padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].

New in version 1.0.0.

padding is a VariableListProperty and defaults to [8dp, 8dp, 8dp, 8dp].

class kivymd.uix.button.button.MDRaisedButton(*args, **kwargs)

A flat button with (by default) a primary color fill and matching color text.

class kivymd.uix.button.button.MDRectangleFlatButton(*args, **kwargs)

A flat button with (by default) a primary color border and primary color text.

class kivymd.uix.button.button.MDRectangleFlatIconButton(*args, **kwargs)

A flat button with (by default) a primary color border, primary color text and a primary color icon on the left.

class kivymd.uix.button.button.MDRoundFlatButton(*args, **kwargs)

A flat button with (by default) fully rounded corners, a primary color border and primary color text.

class kivymd.uix.button.button.MDRoundFlatIconButton(*args, **kwargs)

A flat button with (by default) rounded corners, a primary color border, primary color text and a primary color icon on the left.

class kivymd.uix.button.button.MDFillRoundFlatButton(*args, **kwargs)

A flat button with (by default) rounded corners, a primary color fill and primary color text.

class kivymd.uix.button.button.MDFillRoundFlatIconButton(*args, **kwargs)

A flat button with (by default) rounded corners, a primary color fill, primary color text and a primary color icon on the left.

class kivymd.uix.button.button.MDIconButton(*args, **kwargs)

A simple rounded icon button.

icon

Button icon.

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

set_size(self, interval: Union[int, float])

Sets the icon width/height based on the current icon_size attribute, or the default value if it is zero. The icon size is set to (48, 48) for an icon with the default font_size 24sp.

class kivymd.uix.button.button.MDFloatingActionButton(*args, **kwargs)

Implementation FAB button.

type

Type of M3 button.

New in version 1.0.0.

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

type is an OptionProperty and defaults to ‘standard’.

set_font_size(self, *args)

set__radius(self, *args)

set_size_and_radius(self, *args)

set_size(self, *args)

on_type(self, instance_md_floating_action_button, type: str)

class kivymd.uix.button.button.MDTextButton(**kwargs)

This mixin class provides Button behavior. Please see the button behaviors module documentation for more information.

Events:

on_press

Fired when the button is pressed.

on_release

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

color

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

color is a ColorProperty and defaults to None.

color_disabled

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

color_disabled is a ColorProperty and defaults to None.

animation_label(self)

on_press(self, *args)

on_disabled(self, instance_button, disabled_value)

class kivymd.uix.button.button.MDFloatingActionButtonSpeedDial(**kwargs)

For more information, see in the FloatLayout class documentation.

Events:

on_open

Called when a stack is opened.

on_close

Called when a stack is closed.

on_press_stack_button

Called at the on_press event for the stack button.

on_release_stack_button

Called at the on_press event for the stack button.

icon

Root button icon name.

MDFloatingActionButtonSpeedDial:
    icon: "pencil"

icon is a StringProperty and defaults to ‘plus’.

anchor

Stack anchor. Available options are: ‘right’.

anchor is a OptionProperty and defaults to ‘right’.

label_text_color

Color of floating text labels in (r, g, b, a) or string format.

MDFloatingActionButtonSpeedDial:
    label_text_color: "orange"

label_text_color is a ColorProperty and defaults to None.

label_bg_color

Background color of floating text labels in (r, g, b, a) or string format.

MDFloatingActionButtonSpeedDial:
    label_text_color: "black"
    label_bg_color: "orange"

label_bg_color is a ColorProperty and defaults to [0, 0, 0, 0].

label_radius

The radius of the background of floating text labels.

MDFloatingActionButtonSpeedDial:
    label_text_color: "black"
    label_bg_color: "orange"

label_radius is a ColorProperty and defaults to [0, 0, 0, 0].

data

Must be a dictionary.

{
    'name-icon': 'Text label',
    ...,
    ...,
}

right_pad

If True, the background for the floating text label will increase by the number of pixels specified in the right_pad_value parameter.

Works only if the hint_animation parameter is set to True.

False

MDFloatingActionButtonSpeedDial:
    hint_animation: True
    right_pad: False

True

MDFloatingActionButtonSpeedDial:
    hint_animation: True
    right_pad: True
    right_pad_value: "10dp"

right_pad is a BooleanProperty and defaults to False.

right_pad_value

See right_pad parameter for more information.

right_pad_value is a NumericProperty and defaults to 0.

root_button_anim

If True then the root button will rotate 45 degrees when the stack is opened.

root_button_anim is a BooleanProperty and defaults to False.

opening_transition

The name of the stack opening animation type.

opening_transition is a StringProperty and defaults to ‘out_cubic’.

closing_transition

The name of the stack closing animation type.

closing_transition is a StringProperty and defaults to ‘out_cubic’.

opening_transition_button_rotation

The name of the animation type to rotate the root button when opening the stack.

opening_transition_button_rotation is a StringProperty and defaults to ‘out_cubic’.

closing_transition_button_rotation

The name of the animation type to rotate the root button when closing the stack.

closing_transition_button_rotation is a StringProperty and defaults to ‘out_cubic’.

opening_time

Time required for the stack to go to: attr:state ‘open’.

opening_time is a NumericProperty and defaults to 0.2.

closing_time

Time required for the stack to go to: attr:state ‘close’.

closing_time is a NumericProperty and defaults to 0.2.

opening_time_button_rotation

Time required to rotate the root button 45 degrees during the stack opening animation.

opening_time_button_rotation is a NumericProperty and defaults to 0.2.

closing_time_button_rotation

Time required to rotate the root button 0 degrees during the stack closing animation.

closing_time_button_rotation is a NumericProperty and defaults to 0.2.

state

Indicates whether the stack is closed or open. Available options are: ‘close’, ‘open’.

state is a OptionProperty and defaults to ‘close’.

bg_color_root_button

Background color of root button in (r, g, b, a) or string format.

bg_color_root_button is a ColorProperty and defaults to None.

bg_color_stack_button

Background color of the stack buttons in (r, g, b, a) or string format.

bg_color_stack_button is a ColorProperty and defaults to None.

color_icon_stack_button

The color icon of the stack buttons in (r, g, b, a) or string format.

color_icon_stack_button is a ColorProperty and defaults to None.

color_icon_root_button

The color icon of the root button in (r, g, b, a) or string format.

color_icon_root_button is a ColorProperty and defaults to None.

bg_hint_color

Background color for the floating text of the buttons in (r, g, b, a) or string format.

bg_hint_color is a ColorProperty and defaults to None.

hint_animation

Whether to use button extension animation to display floating text.

hint_animation is a BooleanProperty and defaults to False.

stack_buttons

on_open(self, *args)

Called when a stack is opened.

on_close(self, *args)

Called when a stack is closed.

on_leave(self, instance_button: MDFloatingBottomButton)

Called when the mouse cursor goes outside the button of stack.

on_enter(self, instance_button: MDFloatingBottomButton)

Called when the mouse cursor is over a button from the stack.

on_data(self, instance_speed_dial, data: dict)

Creates a stack of buttons.

on_icon(self, instance_speed_dial, name_icon: str)

on_label_text_color(self, instance_speed_dial, color: list | str)

on_color_icon_stack_button(self, instance_speed_dial, color: list)

on_hint_animation(self, instance_speed_dial, value: bool)

on_bg_hint_color(self, instance_speed_dial, color: list)

on_color_icon_root_button(self, instance_speed_dial, color: list)

on_bg_color_stack_button(self, instance_speed_dial, color: list)

on_bg_color_root_button(self, instance_speed_dial, color: list)

on_press_stack_button(self, *args)

Called at the on_press event for the stack button.

MDFloatingActionButtonSpeedDial:
    on_press_stack_button: print(*args)

New in version 1.1.0.

on_release_stack_button(self, *args)

Called at the on_release event for the stack button.

MDFloatingActionButtonSpeedDial:
    on_release_stack_button: print(*args)

New in version 1.1.0.

set_pos_labels(self, instance_floating_label: MDFloatingLabel)

Sets the position of the floating labels. Called when the application’s root window is resized.

set_pos_root_button(self, instance_floating_root_button: MDFloatingRootButton)

Sets the position of the root button. Called when the application’s root window is resized.

set_pos_bottom_buttons(self, instance_floating_bottom_button: MDFloatingBottomButton)

Sets the position of the bottom buttons in a stack. Called when the application’s root window is resized.

open_stack(self, instance_floating_root_button: MDFloatingRootButton)

Opens a button stack.

do_animation_open_stack(self, anim_data: dict)

Parameters:

anim_data –

{

<kivymd.uix.button.MDFloatingBottomButton object>:

<kivy.animation.Animation>,

<kivymd.uix.button.MDFloatingBottomButton object>:

<kivy.animation.Animation object>,

…,

}

close_stack(self)

Closes the button stack.