MorphUI 0.11.0

MorphUI is a creative and flexible UI extension for Kivy, designed to provide developers with a modern and customizable set of components for building beautiful user interfaces. Unlike KivyMD, MorphUI is not bound to Material Design principles, allowing for greater freedom in design and styling.

MorphUI

MorphUI is a modern, flexible UI framework for Kivy that brings beautiful, themeable components with dynamic color management. Built on Material You's dynamic color system, MorphUI provides an extensive set of widgets with automatic theming, smooth animations, and a powerful component architecture—all while giving you complete design freedom.

✨ Key Features

• 🎨 Dynamic Theming: Material You-inspired dynamic color system with automatic light/dark mode
• 🧩 Rich Component Library: Modern buttons, labels, text fields, dropdowns, layouts, and more
• 📊 Data Visualization: Optional matplotlib integration for charts and plots
• ⚡ Smooth Animations: Built-in ripple effects, hover states, and motion behaviors
• 🎯 Powerful Behaviors: Modular behavior system for easy customization
• 📱 Cross-Platform: Runs on Windows, macOS, Linux, Android, iOS, and web
• 🔧 Developer-Friendly: Clean API with comprehensive docstrings

📦 Installation

Basic Installation

pip install morphui

With Visualization Support

For data visualization features (charts and plots):

pip install morphui[visualization]

From Source

git clone https://github.com/j4ggr/MorphUI.git
cd MorphUI
pip install -e .

🚀 Quick Start

Here's a minimal example to get you started:

from morphui.app import MorphApp
from morphui.uix.boxlayout import MorphBoxLayout
from morphui.uix.label import MorphLabel
from morphui.uix.button import MorphButton

class MyApp(MorphApp):
    def build(self):
        # Configure theme
        self.theme_manager.theme_mode = 'Dark'
        self.theme_manager.seed_color = 'Blue'
        
        # Create layout
        layout = MorphBoxLayout(
            MorphLabel(text="Welcome to MorphUI!"),
            MorphButton(text="Click Me!"),
            orientation='vertical',
            spacing=10,
            padding=20
        )
        
        return layout

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

🎨 Theme System

MorphUI's theme system is built on Material You's dynamic color algorithms, automatically generating harmonious color schemes from a single seed color.

Theme Configuration

from morphui.app import MorphApp

class MyApp(MorphApp):
    def build(self):
        # Set theme mode (Light or Dark)
        self.theme_manager.theme_mode = 'Dark'
        
        # Choose a seed color (any color name from Kivy's colormap)
        self.theme_manager.seed_color = 'Orange'
        
        # Select color scheme variant
        # Options: TONAL_SPOT, VIBRANT, EXPRESSIVE, NEUTRAL, 
        #          MONOCHROME, FIDELITY, CONTENT, RAINBOW, FRUIT_SALAD
        self.theme_manager.color_scheme = 'VIBRANT'
        
        # Adjust contrast (0.0 to 1.0)
        self.theme_manager.color_scheme_contrast = 0.0
        
        return self.create_ui()

Custom Seed Colors

Register your own custom colors:

# Register a custom color with hex value
self.theme_manager.register_seed_color('brand_blue', '#0066CC')
self.theme_manager.seed_color = 'brand_blue'

Runtime Theme Switching

# Toggle between light and dark mode
self.theme_manager.toggle_theme_mode()

# Or set explicitly
self.theme_manager.theme_mode = 'Light'  # or 'Dark'

📚 Core Components

MorphApp

Base application class with integrated theme management:

from morphui.app import MorphApp

class MyApp(MorphApp):
    def build(self):
        # Access theme manager
        self.theme_manager.theme_mode = 'Dark'
        
        # Access typography system
        icon_map = self.typography.icon_map
        
        return your_root_widget

Buttons

MorphButton

Full-featured button with theming and animations:

from morphui.uix.button import MorphButton

button = MorphButton(
    text="Click Me",
    on_release=lambda x: print("Button clicked!")
)

MorphIconButton

Icon-only button for compact interfaces:

from morphui.uix.button import MorphIconButton

icon_btn = MorphIconButton(
    icon='close',  # Material icon name
    on_release=self.close_dialog
)

Labels

MorphLabel

Themed label with auto-sizing:

from morphui.uix.label import MorphLabel

label = MorphLabel(
    text="Hello, MorphUI!",
    auto_width=True,
    auto_height=True
)

MorphIconLabel

Label with an icon:

from morphui.uix.label import MorphIconLabel

icon_label = MorphIconLabel(
    icon='star',
    text="Favorite"
)

Text Fields

MorphTextField

Modern text input with validation:

from morphui.uix.textfield import MorphTextField

text_field = MorphTextField(
    heading_text="Email",
    hint_text="Enter your email",
    required=True,
    validator='email'  # Built-in validators: email, url, int, float
)

# Check validation
if text_field.error:
    print(f"Error: {text_field.error_type}")

MorphTextFieldOutlined

Outlined variant:

from morphui.uix.textfield import MorphTextFieldOutlined

email_field = MorphTextFieldOutlined(
    heading_text="Email Address",
    leading_icon='email',
    validator='email',
    required=True
)

Dropdowns

MorphDropdownFilterField

Searchable dropdown with filtering:

from morphui.uix.dropdown import MorphDropdownFilterField

items = [
    {'label_text': 'Apple', 'normal_leading_icon': 'apple'},
    {'label_text': 'Banana', 'normal_leading_icon': 'fruit-citrus'},
    {'label_text': 'Cherry', 'normal_leading_icon': 'fruit-cherries'}
]

dropdown = MorphDropdownFilterField(
    items=items,
    heading_text='Select Fruit',
    leading_icon='magnify',
    item_release_callback=lambda item, index: print(f"Selected: {item.label_text}")
)

Layouts

MorphUI provides themed versions of all standard Kivy layouts:

from morphui.uix.boxlayout import MorphBoxLayout
from morphui.uix.floatlayout import MorphFloatLayout
from morphui.uix.gridlayout import MorphGridLayout

# BoxLayout with themed widgets as children
layout = MorphBoxLayout(
    widget1,
    widget2,
    widget3,
    orientation='vertical',
    spacing=10,
    padding=20
)

📊 Data Visualization

MorphUI includes optional matplotlib integration for creating beautiful, themed charts.

Basic Chart Example

from morphui.app import MorphApp
from morphui.uix.visualization import MorphChart
import matplotlib.pyplot as plt
import numpy as np

class ChartApp(MorphApp):
    def build(self):
        self.theme_manager.theme_mode = 'Dark'
        
        # Create chart widget
        chart = MorphChart()
        
        # Create matplotlib figure
        x = np.linspace(0, 10, 100)
        y = np.sin(x)
        
        fig, ax = plt.subplots(figsize=(10, 6))
        ax.plot(x, y, linewidth=2)
        ax.set_title('Sine Wave')
        ax.set_xlabel('X')
        ax.set_ylabel('Y')
        ax.grid(True, alpha=0.3)
        
        # Set the figure
        chart.figure = fig
        
        return chart

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

Interactive Features

MorphChart automatically includes:

• Zoom and pan controls
• Home/back/forward navigation
• Save figure option
• Automatic theme-aware styling

See examples/visualization_example.py for more advanced usage.

💡 Complete Examples

Theme Showcase App

from morphui.app import MorphApp
from morphui.uix.boxlayout import MorphBoxLayout
from morphui.uix.label import MorphLabel
from morphui.uix.button import MorphIconButton

class ThemeShowcaseApp(MorphApp):
    def build(self):
        self.theme_manager.theme_mode = 'Dark'
        self.theme_manager.seed_color = 'Orange'
        
        layout = MorphBoxLayout(
            MorphIconButton(
                icon='brightness-3' if self.theme_manager.theme_mode == 'Light' else 'brightness-5',
                on_release=lambda x: self.toggle_theme()
            ),
            MorphLabel(text=f"Current theme: {self.theme_manager.theme_mode}"),
            orientation='vertical',
            spacing=20,
            padding=20
        )
        
        return layout
    
    def toggle_theme(self):
        self.theme_manager.toggle_theme_mode()

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

Icon Picker Example

from morphui.app import MorphApp
from morphui.uix.floatlayout import MorphFloatLayout
from morphui.uix.dropdown import MorphDropdownFilterField

class IconPickerApp(MorphApp):
    def build(self):
        self.theme_manager.theme_mode = 'Dark'
        self.theme_manager.seed_color = 'Blue'
        
        # Create items from available icons
        icon_items = [
            {
                'label_text': icon_name,
                'leading_icon': icon_name,
            }
            for icon_name in sorted(self.typography.icon_map.keys())
        ]
        
        layout = MorphFloatLayout(
            MorphDropdownFilterField(
                identity='icon_picker',
                items=icon_items,
                item_release_callback=self.icon_selected,
                heading_text='Search icons...',
                leading_icon='magnify',
                pos_hint={'center_x': 0.5, 'center_y': 0.9},
                size_hint=(0.8, None),
            )
        )
        
        self.icon_picker = layout.identities.icon_picker
        return layout
    
    def icon_selected(self, item, index):
        self.icon_picker.text = item.label_text
        self.icon_picker.leading_icon = item.label_text

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

📁 Examples Directory

Explore the examples/ directory for complete, runnable applications:

• color_showcase_app.py - Comprehensive color palette showcase with theme switching
• visualization_example.py - Data visualization with multiple chart types

Running Examples

To run an example:

cd examples
python color_showcase_app.py
# or
python visualization_example.py

🎯 Behavior System

MorphUI uses a modular behavior system that allows you to mix and match functionality:

• MorphThemeBehavior - Automatic theme color binding
• MorphHoverBehavior - Mouse hover detection and states
• MorphRippleBehavior - Material-style ripple effects
• MorphScaleBehavior - Scale animations
• MorphElevationBehavior - Shadow and elevation effects
• MorphAutoSizingBehavior - Automatic size calculations
• MorphIdentificationBehavior - Widget identification and lookup

These behaviors are composable and can be mixed into custom widgets.

🛠️ Development

Setting Up Development Environment

git clone https://github.com/j4ggr/MorphUI.git
cd MorphUI
pip install -e ".[test,visualization]"

Running Tests

pytest tests/

📖 Documentation

MorphUI components are extensively documented with docstrings. Access documentation in your IDE or use Python's help system:

from morphui.uix.button import MorphButton
help(MorphButton)

🗺️ Roadmap

• Dynamic color system with Material You
• Core components (buttons, labels, text fields)
• Layout containers
• Data visualization integration
• More advanced components (sliders, switches, progress bars)
• Animation improvements
• Comprehensive documentation website
• PyPI package release
• Performance optimizations

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Guidelines

1. Follow the existing code style
2. Add docstrings to new components
3. Test your changes thoroughly
4. Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on top of the excellent Kivy framework
• Material You color system via material-color-utilities
• Icons from Material Design Icons
• Inspired by modern UI frameworks while maintaining design flexibility

📞 Support

• Issues: GitHub Issues
• Examples: Check the examples/ directory
• Documentation: See docstrings in source code

---

MorphUI - Beautiful, flexible UIs for Kivy applications.