0
# KivyMD
1

2
KivyMD is a comprehensive Material Design component library for Kivy that provides a collection of Material Design compliant widgets and components for building cross-platform, touch-enabled graphical applications. The library includes over 40 UI components including buttons, cards, navigation drawers, app bars, text fields, and complex widgets like data tables and date pickers, all following Google's Material Design specifications.
3

4
## Package Information
5

6
- **Package Name**: kivymd
7
- **Language**: Python
8
- **Installation**: `pip install kivymd`
9
- **Requirements**: `kivy>=2.0.0`, `pillow`
10

11
## Core Imports
12

13
```python
14
import kivymd
15
```
16

17
Common application setup:
18

19
```python
20
from kivymd.app import MDApp
21
from kivymd.theming import ThemeManager
22
```
23

24
Widget imports:
25

26
```python
27
from kivymd.uix.button import MDRaisedButton, MDFlatButton, MDIconButton
28
from kivymd.uix.label import MDLabel
29
from kivymd.uix.textfield import MDTextField
30
from kivymd.uix.card import MDCard
31
from kivymd.uix.list import MDList, OneLineListItem
32
from kivymd.uix.boxlayout import MDBoxLayout
33
from kivymd.uix.gridlayout import MDGridLayout
34
```
35

36
Color and theming imports:
37

38
```python
39
from kivymd.color_definitions import colors, palette
40
from kivymd.theming import ThemableBehavior
41
```
42

43
Utility imports:
44

45
```python
46
from kivymd.toast import toast
47
```
48

49
## Basic Usage
50

51
```python
52
from kivymd.app import MDApp
53
from kivymd.uix.label import MDLabel
54
from kivymd.uix.button import MDRaisedButton
55
from kivymd.uix.boxlayout import MDBoxLayout
56

57
class MainApp(MDApp):
58
    def build(self):
59
        # Create main layout
60
        layout = MDBoxLayout(
61
            orientation="vertical",
62
            adaptive_height=True,
63
            spacing="20dp",
64
            pos_hint={"center_x": 0.5, "center_y": 0.5}
65
        )
66
        
67
        # Add label
68
        label = MDLabel(
69
            text="Hello, Material Design!",
70
            halign="center",
71
            theme_text_color="Primary"
72
        )
73
        
74
        # Add button
75
        button = MDRaisedButton(
76
            text="Click Me",
77
            pos_hint={"center_x": 0.5}
78
        )
79
        
80
        layout.add_widget(label)
81
        layout.add_widget(button)
82
        
83
        return layout
84

85
MainApp().run()
86
```
87

88
## Architecture
89

90
KivyMD follows a structured architecture built on Kivy's foundation:
91

92
- **MDApp**: Main application class with integrated Material Design theming
93
- **ThemeManager**: Central theming system managing colors, fonts, and Material Design specifications
94
- **ThemableBehavior**: Mixin behavior that provides theme integration for all widgets
95
- **Material Widgets**: Complete set of Material Design components (buttons, cards, lists, navigation, etc.)
96
- **Behaviors**: Reusable behaviors for elevation, ripple effects, hover states, and animations
97
- **Layout Classes**: Material Design compliant layout containers
98
- **Resource Definitions**: Complete Material Design color palettes, icons, and typography
99

100
This architecture ensures consistent Material Design aesthetics across all platforms while maintaining Kivy's cross-platform capabilities and performance characteristics.
101

102
## Capabilities
103

104
### Application Framework
105

106
Core application classes and theming system for Material Design applications, including the main app class, theme management, and Material Design resource definitions.
107

108
```python { .api }
109
class MDApp:
110
    """Main application class with Material Design theming."""
111
    def build(self): ...
112
    
113
class ThemeManager:
114
    """Central theme management system."""
115
    primary_palette: str
116
    accent_palette: str
117
    theme_style: str  # "Light" or "Dark"
118
    
119
class ThemableBehavior:
120
    """Mixin behavior for themed widgets."""
121
    theme_cls: ThemeManager
122
```
123

124
[Application Framework](./application.md)
125

126
### Layout Containers
127

128
Material Design layout containers including box layouts, grid layouts, cards, and responsive layouts that follow Material Design spacing and elevation guidelines.
129

130
```python { .api }
131
class MDBoxLayout:
132
    """Material Design box layout."""
133
    orientation: str
134
    adaptive_height: bool
135
    adaptive_width: bool
136
    spacing: str
137
    
138
class MDCard:
139
    """Material Design card container."""
140
    elevation: float
141
    radius: list
142
    md_bg_color: str
143
```
144

145
[Layout Containers](./layouts.md)
146

147
### Buttons & Interactive Elements
148

149
Complete set of Material Design buttons including raised buttons, flat buttons, icon buttons, floating action buttons, and speed dial components.
150

151
```python { .api }
152
class MDRaisedButton:
153
    """Material Design raised button with elevation."""
154
    text: str
155
    theme_text_color: str
156
    md_bg_color: str
157
    
158
class MDIconButton:
159
    """Material Design icon-only button."""
160
    icon: str
161
    theme_icon_color: str
162
    
163
class MDFloatingActionButton:
164
    """Material Design floating action button."""
165
    icon: str
166
    type: str  # "standard" or "large"
167
```
168

169
[Buttons & Interactive Elements](./buttons.md)
170

171
### Text & Input Components
172

173
Text display and input components including labels, icons, text fields, and selection controls following Material Design text and input specifications.
174

175
```python { .api }
176
class MDLabel:
177
    """Material Design label."""
178
    text: str
179
    theme_text_color: str
180
    font_style: str
181
    
182
class MDTextField:
183
    """Material Design text input field."""
184
    hint_text: str
185
    text: str
186
    helper_text: str
187
    error: bool
188
    
189
class MDCheckbox:
190
    """Material Design checkbox."""
191
    active: bool
192
    disabled: bool
193
```
194

195
[Text & Input Components](./text-input.md)
196

197
### Lists & Data Display
198

199
Comprehensive list components including various list item types, data tables, and image lists for displaying structured data with Material Design styling.
200

201
```python { .api }
202
class MDList:
203
    """Material Design list container."""
204
    
205
class OneLineListItem:
206
    """Single line list item."""
207
    text: str
208
    
209
class MDDataTable:
210
    """Material Design data table."""
211
    column_data: list
212
    row_data: list
213
    sorted_on: str
214
```
215

216
[Lists & Data Display](./lists.md)
217

218
### Navigation Components
219

220
Navigation components including app bars, navigation drawers, bottom navigation, tabs, and navigation rails for Material Design navigation patterns.
221

222
```python { .api }
223
class MDTopAppBar:
224
    """Material Design top app bar."""
225
    title: str
226
    left_action_items: list
227
    right_action_items: list
228
    
229
class MDNavigationDrawer:
230
    """Material Design navigation drawer."""
231
    type: str  # "standard" or "modal"
232
    
233
class MDBottomNavigation:
234
    """Material Design bottom navigation."""
235
    panel_color: str
236
```
237

238
[Navigation Components](./navigation.md)
239

240
### Dialogs & Overlays
241

242
Dialog and overlay components including dialogs, bottom sheets, menus, snackbars, and tooltips for Material Design interaction patterns.
243

244
```python { .api }
245
class MDDialog:
246
    """Material Design dialog."""
247
    title: str
248
    text: str
249
    buttons: list
250
    
251
class MDBottomSheet:
252
    """Material Design bottom sheet."""
253
    
254
class MDDropdownMenu:
255
    """Material Design dropdown menu."""
256
    items: list
257
    width_mult: float
258
```
259

260
[Dialogs & Overlays](./dialogs.md)
261

262
### Advanced Components
263

264
Advanced UI components including date/time pickers, expansion panels, chips, segmented controls, and specialized widgets for complex interactions.
265

266
```python { .api }
267
class MDDatePicker:
268
    """Material Design date picker."""
269
    year: int
270
    month: int
271
    day: int
272
    
273
class MDExpansionPanel:
274
    """Material Design expansion panel."""
275
    content: object
276
    panel_cls: object
277
    
278
class MDChip:
279
    """Material Design chip."""
280
    text: str
281
    icon: str
282
    check: bool
283
```
284

285
[Advanced Components](./advanced.md)
286

287
### Animations & Effects
288

289
Animation and visual effect components including transitions, hero animations, ripple effects, and elevation behaviors for Material Design motion.
290

291
```python { .api }
292
class MDFadeSlideTransition:
293
    """Fade slide transition for screen manager."""
294
    
295
class MDHeroFrom:
296
    """Hero animation source widget."""
297
    tag: str
298
    
299
class CircularRippleBehavior:
300
    """Circular ripple effect behavior."""
301
    ripple_color: str
302
    ripple_alpha: float
303
```
304

305
[Animations & Effects](./animations.md)
306

307
### Utility Functions
308

309
Utility functions for common operations and cross-platform functionality.
310

311
```python { .api }
312
def toast(text: str = "", background: list = None, duration: float = 2.5):
313
    """
314
    Display cross-platform toast notification.
315
    
316
    Shows a brief message to the user that disappears automatically
317
    after the specified duration. Implementation varies by platform.
318
    
319
    Args:
320
        text (str): Message text to display (default: "")
321
        background (list): Background color as [r, g, b, a] values (default: None)
322
        duration (float): Display duration in seconds (default: 2.5)
323
    """
324
```
325

326
## Types
327

328
```python { .api }
329
# Common type definitions used across KivyMD components
330

331
# Color specifications
332
ColorType = str | tuple | list  # Color as string name, hex, or RGB/RGBA values
333

334
# Spacing and sizing
335
SpacingType = str | int | float  # Spacing as dp string or numeric value
336

337
# Icon specifications  
338
IconType = str  # Material Design icon name from md_icons
339

340
# Theme specifications
341
ThemeStyle = str  # "Light" or "Dark"
342
PaletteType = str  # Color palette name (e.g., "Red", "Blue", "Green")
343
FontStyle = str  # Font style name (e.g., "H1", "H2", "Body1", "Caption")
344

345
# Widget sizing
346
SizeHintType = tuple | None  # Size hint as (width, height) or None
347
AdaptiveSizeType = bool  # Whether widget should adapt to content size
348

349
# Touch and interaction
350
RippleColorType = str | tuple  # Ripple effect color specification
351
ElevationType = int | float  # Elevation level (0-24)
352

353
# List and menu item data
354
ListItemType = dict  # Dictionary with "text", "icon", and callback keys
355
MenuItemType = dict  # Dictionary with "text", "icon", "on_release" keys
356

357
# Transition types
358
TransitionType = str  # Transition name for screen manager
359
```