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 DeclarativeBehavior and RectangularRippleBehavior and ThemableBehavior and ButtonBehavior and AnchorLayout classes 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.

For more information, see in the BaseButton and ButtonContentsText classes 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 [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.

For more information, see in the BaseButton and ButtonElevationBehaviour and ButtonContentsText classes documentation.

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

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

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

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.

For more information, see in the BaseButton and OldButtonIconMixin and ButtonContentsIconText classes documentation.

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.

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

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.

For more information, see in the BaseButton and OldButtonIconMixin and ButtonContentsIconText classes documentation.

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

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

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

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.

For more information, see in the BaseButton and OldButtonIconMixin and ButtonContentsIconText classes documentation.

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

A simple rounded icon button.

For more information, see in the BaseButton and OldButtonIconMixin and ButtonContentsIcon classes documentation.

icon

Button icon.

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

set_size(self, interval: 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.

For more information, see in the BaseButton and OldButtonIconMixin and ButtonElevationBehaviour and ButtonContentsIcon classes documentation.

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)

Text button class.

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

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.

For more information, see in the DeclarativeBehavior and ThemableBehavior and FloatLayout lasses 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.

MDFloatingActionButtonSpeedDial:
    bg_color_root_button: "red"

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.

MDFloatingActionButtonSpeedDial:
    bg_color_root_button: "red"
    bg_color_stack_button: "red"

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.

MDFloatingActionButtonSpeedDial:
    bg_color_root_button: "red"
    bg_color_stack_button: "red"
    color_icon_stack_button: "white"

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.

MDFloatingActionButtonSpeedDial:
    bg_color_root_button: "red"
    bg_color_stack_button: "red"
    color_icon_stack_button: "white"
    color_icon_root_button: self.color_icon_stack_button

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.

MDFloatingActionButtonSpeedDial:
    bg_hint_color: "red"
    hint_animation: True

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.