Button#
#
See also
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:
Elevated button
Filled button
Filled tonal button
Outlined button
Text button
Icon button
Segmented button
Floating action button (FAB)
Extended FAB
Common buttons#
Buttons help people take action, such as sending an email, sharing a document, or liking a comment.
Elevated button
Filled button
Filled tonal button
Outlined button
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()
from kivymd.app import MDApp
from kivymd.uix.button import MDButton, MDButtonIcon, MDButtonText
from kivymd.uix.screen import MDScreen
class Example(MDApp):
def build(self):
self.theme_cls.primary_palette = "Green"
return (
MDScreen(
MDButton(
MDButtonIcon(
icon="plus",
),
MDButtonText(
text="Elevated",
),
style="elevated",
pos_hint={"center_x": 0.5, "center_y": 0.5},
),
md_bg_color=self.theme_cls.surfaceColor,
)
)
Example().run()
Common buttons can contain an icon or be without an icon:
MDButton:
style: "elevated"
text: "Elevated"
Filled#
MDButton:
style: "filled"
MDButtonText:
text: "Filled"
Tonal#
MDButton:
style: "tonal"
MDButtonText:
text: "Tonal"
Outlined#
MDButton:
style: "outlined"
MDButtonText:
text: "Outlined"
Text#
MDButton:
style: "text"
MDButtonText:
text: "Text"
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}
Font of the button text#
MDButton:
style: "filled"
MDButtonIcon:
icon: "plus"
MDButtonText:
text: "Filled"
font_style: "Title"
MDButton:
style: "elevated"
MDButtonText:
text: "Elevated"
theme_font_name: "Custom"
font_name: "path/to/font.ttf"
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"
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.
See also
Standard icon button
Contained icon button (including filled, filled tonal, and outlined styles)
StandardIcon FilledIcon TonalIcon OutlinedIcon
StandardIcon#
MDIconButton:
icon: "heart-outline"
style: "standard"
FilledIcon#
MDIconButton:
icon: "heart-outline"
style: "filled"
TonalIcon#
MDIconButton:
icon: "heart-outline"
style: "tonal"
OutlinedIcon#
MDIconButton:
icon: "heart-outline"
style: "outlined"
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"
Custom button color#
MDIconButton:
icon: "heart-outline"
style: "tonal"
theme_bg_color: "Custom"
md_bg_color: "brown"
theme_icon_color: "Custom"
icon_color: "white"
FAB buttons#
The FAB represents the most important action on a screen. It puts key actions within reach.
See also
Standard FAB
Small FAB
Large FAB
There are three sizes of floating action buttons: FAB, small FAB, and large FAB:
Standard#
MDFabButton:
icon: "pencil-outline"
style: "standard"
Small#
MDFabButton:
icon: "pencil-outline"
style: "small"
Large#
MDFabButton:
icon: "pencil-outline"
style: "large"
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.
Surface
Secondary
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):
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()
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.
Extended FAB with both icon and label text
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()
Without icon#
MDExtendedFabButton:
fab_state: "expand"
MDExtendedFabButtonText:
text: "Compose"
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
andMDFabButton
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 anDictProperty
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 anOptionProperty
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 aColorProperty
and defaults to None.
- style#
Button type.
Available options are: ‘standard’, ‘small’, ‘large’.
style
is anOptionProperty
and defaults to ‘standard’.
- fab_state#
The state of the button.
Available options are: ‘collapse’ or ‘expand’.
fab_state
is anOptionProperty
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 aColorProperty
and defaults to None.
- radius#
Canvas radius.
radius
is anVariableListProperty
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
andBackgroundColorBehavior
andRectangularRippleBehavior
andButtonBehavior
andThemableBehavior
andStateLayerBehavior
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 anDictProperty
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 aColorProperty
and defaults to None.
- shadow_radius#
Button shadow radius.
shadow_radius
is anVariableListProperty
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 aColorProperty
and defaults to None.
- line_color#
Outlined color.
line_color
is aColorProperty
and defaults to None.
- line_width#
Line width for button border.
line_width
is aNumericProperty
and defaults to 1.
- 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
andBaseButton
andRelativeLayout
classes documentation.- style#
Button type.
Available options are: ‘filled’, ‘elevated’, ‘outlined’, ‘tonal’, ‘text’.
style
is anOptionProperty
and defaults to ‘elevated’.
- radius#
Button radius.
radius
is anVariableListProperty
and defaults to [dp(20), dp(20), dp(20), dp(20)].
- 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.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- 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
andButtonBehavior
andMDIcon
classes documentation.- style#
Button type.
New in version 2.0.0.
Available options are: ‘standard’, ‘filled’, ‘tonal’, ‘outlined’.
style
is anOptionProperty
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 aColorProperty
and defaults to None.
- class kivymd.uix.button.button.MDFabButton(**kwargs)#
Base class for FAB buttons.
For more information, see in the
BaseFabButton
andCommonElevationBehavior
andRectangularRippleBehavior
andButtonBehavior
andMDIcon
classes documentation.
- 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
andThemableBehavior
andMotionExtendedFabButtonBehavior
andCommonElevationBehavior
andStateLayerBehavior
andBaseFabButton
andButtonBehavior
andRelativeLayout
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 anDictProperty
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.
- widget:
>>> 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.