Button

Buttons trigger actions. MorphUI provides several button variants — from full text buttons with ripple and elevation to compact icon-only buttons.

Variants

Class	Use case
MorphButton	Primary action button with text and optional icons
MorphIconButton	Icon-only button (leading icon)
MorphTrailingIconButton	Icon-only button (trailing)
MorphIconTextButton	Icon + text, icon on the left
MorphTextIconButton	Text + icon, icon on the right
MorphTextIconToggleButton	Toggle version of text+icon button
MorphSimpleIconButton	Lightweight icon button (no elevation)

Usage

from morphui.uix.button import MorphButton, MorphIconButton, MorphIconTextButton

# Text button
btn = MorphButton(text="Save", on_release=self.save)

# Icon button
icon_btn = MorphIconButton(icon='content-save', on_release=self.save)

# Icon + text
combo = MorphIconTextButton(icon='plus', text="Add item")

Tooltips

All button variants accept a tooltip keyword:

from morphui.uix.tooltip import MorphSimpleTooltip

btn = MorphIconButton(
    icon='delete',
    tooltip=MorphSimpleTooltip(text="Delete selected"),
)

---

morphui.uix.button

Button widgets for MorphUI.

This module provides button and icon button widgets built on top of Kivy's Label with a full set of MorphUI behaviors: ripple effects, hover states, elevation, theming, and optional tooltips.

CLASS	DESCRIPTION
MorphSimpleIconButton	Lightweight icon button — no elevation, designed for use inside other components such as chips or text fields.
MorphButton	Full-featured text button with theming, ripple, hover, and optional leading/trailing icons.
MorphIconButton	Icon-only button variant.
MorphTrailingIconButton	Icon-only button variant for trailing positions.
MorphIconTextButton	Icon on the left, text label on the right.
MorphTextIconButton	Text label on the left, icon on the right.
MorphTextIconToggleButton	Toggleable version of MorphTextIconButton.

MorphSimpleIconButton(**kwargs)

Bases: MorphAutoSizingBehavior, MorphIconBehavior, MorphRoundSidesBehavior, MorphIdentificationBehavior, MorphThemeBehavior, MorphHoverBehavior, MorphRippleBehavior, MorphInteractionLayerBehavior, MorphContentLayerBehavior, MorphButtonBehavior, MorphTooltipBehavior, Label

A simple icon button widget with ripple effect and MorphUI theming.

This class is a lightweight button designed for displaying icons with ripple effects and theming support. It is useful for scenarios where a full-featured button is not required but icon interaction is needed (e.g., toolbar buttons, or within a chip).

default_config = dict(theme_color_bindings={'normal_surface_color': 'transparent_color', 'normal_content_color': 'content_surface_color', 'hovered_content_color': 'inverse_surface_color', 'disabled_content_color': 'content_surface_variant_color'}, typography_role=(MorphIconLabel.default_config['typography_role']), typography_size=(MorphIconLabel.default_config['typography_size']), font_name=(MorphIconLabel.default_config['font_name']), halign='center', valign='center', ripple_enabled=True, ripple_color=None, ripple_layer='interaction', padding=(dp(8)), auto_size=True) class-attribute instance-attribute

Default configuration values for MorphSimpleIconButton.

Provides standard icon button appearance and behavior settings: - Center alignment for icon visibility - Middle vertical alignment for centered appearance - Bounded colors for theme integration - Ripple effect for touch feedback - Auto-sizing to fit content These values can be overridden by subclasses or during instantiation.

MorphButton(**kwargs)

Bases: MorphTooltipBehavior, MorphRoundSidesBehavior, MorphIdentificationBehavior, MorphHoverBehavior, MorphThemeBehavior, MorphRippleBehavior, MorphCompleteLayerBehavior, MorphButtonBehavior, MorphAutoSizingBehavior, MorphElevationBehavior, Label

A button widget with ripple effect and MorphUI theming.

This class combines Kivy's TouchRippleButtonBehavior with MorphUI's MorphLabel to create a button that supports ripple effects and theming.

default_config = dict(halign='center', valign='center', theme_style='container', ripple_enabled=True, ripple_color=None, ripple_layer='interaction', padding=(dp(8)), auto_size=True) class-attribute instance-attribute

Default configuration values for MorphButton.

Provides standard button appearance and behavior settings: - Center alignment for text readability - Middle vertical alignment for centered appearance - Bounded colors for theme integration - Ripple effect for touch feedback - Auto-sizing to fit content

These values can be overridden by subclasses or during instantiation.

MorphIconButton(**kwargs)

Bases: MorphIconBehavior, MorphButton

A button widget designed for icon display with ripple effect and MorphUI theming.

This class is similar to MorphButton but is intended for use with icon fonts or images, providing a button that supports ripple effects and theming.

default_config = dict(font_name=(MorphIconLabel.default_config['font_name']), halign='center', valign='center', theme_style='container', typography_role=(MorphIconLabel.default_config['typography_role']), typography_size=(MorphIconLabel.default_config['typography_size']), ripple_enabled=True, ripple_color=None, ripple_layer='interaction', auto_size=True, padding=(dp(8)), radius=([dp(5)] * 4)) class-attribute instance-attribute

Default configuration values for MorphIconButton.

Provides standard icon button appearance and behavior settings: - Center alignment for icon visibility - Middle vertical alignment for centered appearance - Bounded colors for theme integration - Ripple effect for touch feedback - Auto-sizing to fit content - Rounded corners for a modern look

These values can be overridden by subclasses or during instantiation.

MorphTrailingIconButton(**kwargs)

Bases: MorphScaleBehavior, MorphSimpleIconButton

Trailing icon button for containers.

This widget displays an interactive icon button on the right side of a container, with support for scale animations. Used primarily for chips where the trailing icon needs button behavior.

MorphIconTextButton(**kwargs)

Bases: MorphIconBehavior, MorphTooltipBehavior, MorphRoundSidesBehavior, MorphDelegatedThemeBehavior, MorphHoverBehavior, MorphThemeBehavior, MorphRippleBehavior, MorphCompleteLayerBehavior, MorphButtonBehavior, MorphElevationBehavior, MorphIconLabelContainer

A button widget that combines icon and text display with ripple effect and MorphUI theming.

This class extends MorphIconLabelContainer to create a button that supports both icon and text content, along with ripple effects and theming.

Examples:

Simple usage of MorphIconTextButton in a MorphApp:

from morphui.app import MorphApp
from morphui.uix.button import MorphIconTextButton
from morphui.uix.floatlayout import MorphFloatLayout

class MyApp(MorphApp):
    def build(self) -> MorphFloatLayout:
        self.theme_manager.seed_color = 'morphui_teal'
        self.theme_manager.switch_to_dark()
        return MorphFloatLayout(
            MorphIconTextButton(
                identity='icon_text_button',
                normal_icon='language-python',
                label_text='Icon Text Button',
                pos_hint={'center_x': 0.5, 'center_y': 0.5},),)

if __name__ == '__main__':
    MyApp().run()

Toggle behavior with MorphToggleButtonBehavior: ```python from morphui.app import MorphApp from morphui.uix.button import MorphIconTextButton from morphui.uix.floatlayout import MorphFloatLayout from morphui.uix.behaviors import MorphToggleButtonBehavior

class ToggleIconTextButton( MorphIconTextButton, MorphToggleButtonBehavior): pass

class MyApp(MorphApp): def build(self) -> MorphFloatLayout: self.theme_manager.seed_color = 'morphui_teal' self.theme_manager.switch_to_dark() return MorphFloatLayout( ToggleIconTextButton( identity='icon_text_button', normal_icon='language-python', active_icon='language-java', label_text='Icon Text Button', pos_hint={'center_x': 0.5, 'center_y': 0.5},),)

if name == 'main': MyApp().run()

default_child_classes = {'leading_widget': MorphButtonLeadingIconLabel, 'label_widget': MorphButtonTextLabel} class-attribute instance-attribute

Default child widgets for MorphIconTextButton.

• leading_widget: An instance of :class:~morphui.uix.label. MorphButtonLeadingIconLabel for displaying the leading icon.
• label_widget: An instance of :class:~morphui.uix.label. MorphButtonTextLabel for displaying the button text.

default_config = dict(theme_style='container', orientation='horizontal', ripple_enabled=True, ripple_color=None, ripple_layer='interaction', padding=(dp(8)), spacing=(dp(4)), radius=(dp(4)), auto_size=True, delegate_content_color=True) class-attribute instance-attribute

Default configuration values for MorphIconTextButton.

Provides standard button appearance and behavior settings: - Bounded colors for theme integration - Ripple effect for touch feedback - Auto-sizing to fit content - Delegation of content color theming to child widgets These values can be overridden by subclasses or during instantiation.

MorphTextIconButton(**kwargs)

Bases: MorphIconBehavior, MorphTooltipBehavior, MorphRoundSidesBehavior, MorphDelegatedThemeBehavior, MorphHoverBehavior, MorphThemeBehavior, MorphRippleBehavior, MorphCompleteLayerBehavior, MorphButtonBehavior, MorphElevationBehavior, MorphLabelIconContainer

A button widget that combines text and icon display with ripple effect and MorphUI theming.

This class extends MorphIconTextButton to create a button that primarily displays text with an optional trailing icon, along with ripple effects and theming.

default_child_classes = {'label_widget': MorphButtonTextLabel, 'trailing_widget': MorphButtonTrailingIconLabel} class-attribute instance-attribute

Default child widgets for MorphTextIconButton.

• label_widget: An instance of :class:~morphui.uix.label. MorphButtonTextLabel for displaying the button text.
• trailing_widget: An instance of :class:~morphui.uix.label. MorphButtonTrailingIconLabel for displaying the trailing icon.

default_config = MorphIconTextButton.default_config.copy() class-attribute instance-attribute

Default configuration values for MorphTextIconButton.

Inherits default configuration from :class:MorphIconTextButton.

MorphTextIconToggleButton(**kwargs)

Bases: MorphToggleButtonBehavior, MorphTextIconButton

A toggle button widget that combines text and icon display with ripple effect and MorphUI theming.

This class extends MorphTextIconButton and adds toggle behavior, allowing the button to switch between active and inactive states. By default, it uses 'chevron-down' and 'chevron-up' icons to indicate the toggle state.

MorphChipTrailingIconButton(**kwargs)

Bases: MorphTrailingIconButton

Trailing icon button for chips.

Inherits from :class:~morphui.uix.button.MorphTrailingIconButton.

MorphTextFieldTrailingIconButton(**kwargs)

Bases: MorphIconButton

Trailing icon button for text fields.

Used primarily in text fields where the trailing icon needs button behavior (e.g., clear text button).

disabled = BooleanProperty(False) class-attribute instance-attribute

Indicates whether the button is disabled.

When True, the label is rendered in a disabled state, typically with a different color or style to indicate it is not interactive.

:attr:disabled is a :class:kivy.properties.BooleanProperty and defaults to False.

focus = BooleanProperty(False) class-attribute instance-attribute

Indicates whether the button is focused.

When set to True, the button is considered focused, which may affect its visual appearance and behavior.

:attr:focus is a :class:kivy.properties.BooleanProperty and defaults to False.

error = BooleanProperty(False) class-attribute instance-attribute

Indicates whether the button is in an error state.

When set to True, the button is considered to be in an error state, which may affect its visual appearance and behavior.

:attr:error is a :class:kivy.properties.BooleanProperty and defaults to False.

MorphDatePickerDayButton(**kwargs)

Bases: MorphRoundSidesBehavior, MorphIdentificationBehavior, MorphToggleButtonBehavior, MorphThemeBehavior, MorphContentLayerBehavior, MorphSurfaceLayerBehavior, MorphHighlightLayerBehavior, Label

A button widget representing a day in a date picker.

This class combines various MorphUI behaviors to create a button that represents a day in a date picker, with support for ripple effects, theming, and toggle behavior.

date_value = ObjectProperty(None) class-attribute instance-attribute

The date value represented by the button.

This property holds the date value that the button represents.

:attr:date_value is a :class:kivy.properties.ObjectProperty and defaults to None.

is_start_day = BooleanProperty(False) class-attribute instance-attribute

Indicates whether the button represents the start day of a selected date range.

When True, the button is styled to indicate it is the start day of a selected date range.

:attr:is_start_day is a :class:kivy.properties.BooleanProperty and defaults to False.

is_end_day = BooleanProperty(False) class-attribute instance-attribute

Indicates whether the button represents the end day of a selected date range.

When True, the button is styled to indicate it is the end day of a selected date range.

:attr:is_end_day is a :class:kivy.properties.BooleanProperty and defaults to False.

is_in_range = BooleanProperty(False) class-attribute instance-attribute

Indicates whether the button is between the start and end days of a selected date range.

When True, the button is styled to indicate it is between the start and end days of a selected date range.

:attr:is_in_range is a :class:kivy.properties.BooleanProperty and defaults to False.

is_today = BooleanProperty(False) class-attribute instance-attribute

Indicates whether the button represents today's date.

When True, the button is styled to indicate it represents today's date.

:attr:is_today is a :class:kivy.properties.BooleanProperty and defaults to False.

today_border_color = ColorProperty([0, 0, 0, 0]) class-attribute instance-attribute

Border color for today's date button.

This property holds the RGBA color value used for the border of the button when it represents today's date.

:attr:today_border_color is a :class:~kivy.properties.ColorProperty and defaults to [0, 0, 0, 0].

on_date_value(instance, date_value)

Handle changes to the date_value property.

This method is called whenever the date_value property changes. It can be used to update the button's appearance or behavior based on the new date value.