0
# Dialogs & Overlays
1
2
Dialog and overlay components for presenting focused content, actions, and information that appears above the main interface. These components include dialogs, bottom sheets, menus, snackbars, and tooltips that follow Material Design interaction patterns.
3
4
## Capabilities
5
6
### Dialogs
7
8
Modal dialogs for presenting focused content and actions to users.
9
10
```python { .api }
11
class BaseDialog:
12
"""
13
Base class for dialog implementations.
14
15
Foundation class providing common dialog functionality and styling.
16
"""
17
auto_dismiss: bool # Dismiss dialog when touching outside
18
19
def open(self):
20
"""Open the dialog."""
21
22
def dismiss(self):
23
"""Close the dialog."""
24
25
class MDDialog:
26
"""
27
Material Design dialog.
28
29
Modal dialog for displaying focused content, confirmations, or forms
30
with Material Design styling and animations.
31
"""
32
# Content
33
title: str # Dialog title text
34
text: str # Dialog body text
35
buttons: list # List of dialog action buttons
36
items: list # List of dialog items (alternative to text)
37
38
# Visual styling
39
md_bg_color: str | list # Background color
40
elevation: float # Dialog elevation
41
radius: list # Corner radius
42
43
# Sizing and positioning
44
size_hint: tuple # Dialog size hint
45
auto_dismiss: bool # Auto dismiss on outside touch
46
47
# Callbacks
48
def on_open(self):
49
"""Called when dialog opens."""
50
51
def on_dismiss(self):
52
"""Called when dialog is dismissed."""
53
```
54
55
### Bottom Sheets
56
57
Bottom sheets that slide up from the bottom to present additional content or actions.
58
59
```python { .api }
60
class MDBottomSheet:
61
"""
62
Base Material Design bottom sheet.
63
64
Container that slides up from the bottom of the screen to display
65
additional content or actions.
66
"""
67
animation: bool # Enable open/close animations
68
duration_opening: float # Opening animation duration
69
duration_closing: float # Closing animation duration
70
71
# Behavior
72
auto_dismiss: bool # Auto dismiss when touching outside
73
74
def open(self):
75
"""Open the bottom sheet."""
76
77
def dismiss(self):
78
"""Close the bottom sheet."""
79
80
class MDCustomBottomSheet:
81
"""
82
Custom Material Design bottom sheet.
83
84
Bottom sheet with custom content that can contain any widgets.
85
"""
86
screen: object # Screen content to display
87
88
class MDListBottomSheet:
89
"""
90
List-style Material Design bottom sheet.
91
92
Bottom sheet that displays a list of selectable items.
93
"""
94
sheet_list: list # List of sheet items
95
96
def add_item(self, text: str, callback=None):
97
"""
98
Add item to bottom sheet.
99
100
Args:
101
text (str): Item text
102
callback: Function to call when item is selected
103
"""
104
105
class MDGridBottomSheet:
106
"""
107
Grid-style Material Design bottom sheet.
108
109
Bottom sheet that displays items in a grid layout.
110
"""
111
sheet_list: list # List of sheet items with icons
112
113
class GridBottomSheetItem:
114
"""
115
Grid item for grid bottom sheet.
116
117
Individual item in a grid bottom sheet with icon and text.
118
"""
119
text: str # Item text
120
icon: str # Item icon from md_icons
121
122
def on_release(self):
123
"""Called when item is selected."""
124
```
125
126
### Menus
127
128
Dropdown and context menus for presenting lists of actions or options.
129
130
```python { .api }
131
class MDDropdownMenu:
132
"""
133
Material Design dropdown menu.
134
135
Floating menu that appears below or above its caller, containing
136
a list of selectable actions or options.
137
"""
138
# Menu items
139
items: list # List of menu items: [{"text": "...", "icon": "...", "on_release": callback}, ...]
140
141
# Positioning
142
caller: object # Widget that triggers the menu
143
position: str # Menu position: "bottom", "top", "center", "auto"
144
145
# Sizing
146
width_mult: float # Width multiplier relative to caller
147
max_height: str # Maximum menu height (e.g., "200dp")
148
149
# Visual styling
150
elevation: float # Menu elevation
151
radius: list # Corner radius
152
153
# Behavior
154
auto_dismiss: bool # Auto dismiss when item selected
155
156
def open(self):
157
"""Open the dropdown menu."""
158
159
def dismiss(self):
160
"""Close the dropdown menu."""
161
162
def check_position_caller(self, caller):
163
"""
164
Check and adjust menu position relative to caller.
165
166
Args:
167
caller: Widget that triggered the menu
168
"""
169
```
170
171
### Snackbars
172
173
Temporary messages that appear at the bottom of the screen.
174
175
```python { .api }
176
class BaseSnackbar:
177
"""
178
Base snackbar implementation.
179
180
Foundation class for snackbar functionality.
181
"""
182
snackbar_animation_dir: str # Animation direction
183
184
class Snackbar:
185
"""
186
Material Design snackbar.
187
188
Brief message that appears temporarily at the bottom of the screen
189
to provide feedback about an operation.
190
"""
191
text: str # Snackbar message text
192
snackbar_x: str # X position (e.g., "10dp")
193
snackbar_y: str # Y position (e.g., "10dp")
194
size_hint_x: float # Width size hint
195
196
# Action button
197
button_text: str # Action button text
198
button_callback: object # Action button callback
199
200
# Visual styling
201
bg_color: str | list # Background color
202
buttons_color: str | list # Button text color
203
204
# Timing
205
duration: float # Display duration in seconds
206
207
def open(self):
208
"""Show the snackbar."""
209
210
def dismiss(self):
211
"""Hide the snackbar."""
212
```
213
214
### Tooltips
215
216
Hover tooltips that provide additional information about UI elements.
217
218
```python { .api }
219
class MDTooltip:
220
"""
221
Material Design tooltip behavior.
222
223
Mixin behavior that adds tooltip functionality to widgets.
224
Displays informational text when hovering over the widget.
225
"""
226
tooltip_text: str # Tooltip text content
227
tooltip_font_size: str # Tooltip font size (e.g., "14sp")
228
tooltip_radius: list # Tooltip corner radius
229
tooltip_bg_color: str | list # Tooltip background color
230
tooltip_text_color: str | list # Tooltip text color
231
232
# Positioning
233
tooltip_pos_x: float # X offset from widget
234
tooltip_pos_y: float # Y offset from widget
235
236
# Timing
237
tooltip_display_delay: float # Delay before showing tooltip
238
tooltip_hide_delay: float # Delay before hiding tooltip
239
240
def display_tooltip(self):
241
"""Display the tooltip."""
242
243
def hide_tooltip(self):
244
"""Hide the tooltip."""
245
246
class MDTooltipViewClass:
247
"""
248
Tooltip view implementation.
249
250
The visual tooltip widget that contains the tooltip content.
251
"""
252
tooltip_text: str # Tooltip text
253
254
# Visual properties
255
md_bg_color: str | list # Background color
256
radius: list # Corner radius
257
elevation: float # Tooltip elevation
258
```
259
260
## Usage Examples
261
262
### Basic Dialog
263
264
```python
265
from kivymd.uix.dialog import MDDialog
266
from kivymd.uix.button import MDFlatButton, MDRaisedButton
267
268
class MyApp(MDApp):
269
def show_dialog(self):
270
# Create dialog buttons
271
close_button = MDFlatButton(
272
text="CANCEL",
273
on_release=self.close_dialog
274
)
275
276
confirm_button = MDRaisedButton(
277
text="CONFIRM",
278
on_release=self.confirm_action
279
)
280
281
# Create dialog
282
self.dialog = MDDialog(
283
title="Confirm Action",
284
text="Are you sure you want to delete this item? This action cannot be undone.",
285
buttons=[close_button, confirm_button],
286
size_hint=(0.8, None),
287
height="200dp"
288
)
289
290
self.dialog.open()
291
292
def close_dialog(self, instance):
293
"""Close dialog without action."""
294
self.dialog.dismiss()
295
296
def confirm_action(self, instance):
297
"""Handle confirmation."""
298
print("Action confirmed")
299
self.dialog.dismiss()
300
```
301
302
### Bottom Sheet Menu
303
304
```python
305
from kivymd.uix.bottomsheet import MDListBottomSheet
306
307
class MyApp(MDApp):
308
def show_bottom_sheet(self):
309
# Create bottom sheet
310
bottom_sheet = MDListBottomSheet()
311
312
# Add menu items
313
menu_items = [
314
("Share", "share"),
315
("Copy Link", "content-copy"),
316
("Edit", "pencil"),
317
("Delete", "delete"),
318
("Archive", "archive")
319
]
320
321
for text, icon in menu_items:
322
bottom_sheet.add_item(
323
text=text,
324
callback=lambda x, action=text: self.handle_action(action)
325
)
326
327
bottom_sheet.open()
328
329
def handle_action(self, action):
330
"""Handle bottom sheet action."""
331
print(f"Action selected: {action}")
332
```
333
334
### Dropdown Menu
335
336
```python
337
from kivymd.uix.menu import MDDropdownMenu
338
from kivymd.uix.button import MDRaisedButton
339
340
class MyApp(MDApp):
341
def build(self):
342
# Menu trigger button
343
self.menu_button = MDRaisedButton(
344
text="Open Menu",
345
pos_hint={"center_x": 0.5, "center_y": 0.5},
346
on_release=self.open_menu
347
)
348
349
# Create dropdown menu
350
menu_items = [
351
{
352
"text": "New File",
353
"icon": "file-plus",
354
"on_release": lambda: self.menu_callback("New File")
355
},
356
{
357
"text": "Open File",
358
"icon": "folder-open",
359
"on_release": lambda: self.menu_callback("Open File")
360
},
361
{
362
"text": "Save File",
363
"icon": "content-save",
364
"on_release": lambda: self.menu_callback("Save File")
365
},
366
{
367
"text": "Settings",
368
"icon": "cog",
369
"on_release": lambda: self.menu_callback("Settings")
370
}
371
]
372
373
self.menu = MDDropdownMenu(
374
caller=self.menu_button,
375
items=menu_items,
376
width_mult=4,
377
position="bottom"
378
)
379
380
return self.menu_button
381
382
def open_menu(self, instance):
383
"""Open dropdown menu."""
384
self.menu.open()
385
386
def menu_callback(self, action):
387
"""Handle menu item selection."""
388
print(f"Menu item selected: {action}")
389
self.menu.dismiss()
390
```
391
392
### Snackbar Notifications
393
394
```python
395
from kivymd.uix.snackbar import Snackbar
396
397
class MyApp(MDApp):
398
def show_snackbar(self, message, action_text=None, action_callback=None):
399
"""Show snackbar notification."""
400
snackbar = Snackbar(
401
text=message,
402
snackbar_x="10dp",
403
snackbar_y="10dp",
404
size_hint_x=0.9,
405
duration=3.0
406
)
407
408
# Add action button if provided
409
if action_text and action_callback:
410
snackbar.button_text = action_text
411
snackbar.button_callback = action_callback
412
413
snackbar.open()
414
415
def handle_save(self):
416
"""Example save action with snackbar feedback."""
417
# Simulate save operation
418
success = True
419
420
if success:
421
self.show_snackbar(
422
"File saved successfully",
423
"UNDO",
424
self.undo_save
425
)
426
else:
427
self.show_snackbar("Error saving file")
428
429
def undo_save(self, instance):
430
"""Handle undo action."""
431
print("Save undone")
432
self.show_snackbar("Save undone")
433
```
434
435
### Custom Dialog with Form
436
437
```python
438
from kivymd.uix.dialog import MDDialog
439
from kivymd.uix.textfield import MDTextField
440
from kivymd.uix.button import MDFlatButton, MDRaisedButton
441
from kivymd.uix.boxlayout import MDBoxLayout
442
443
class MyApp(MDApp):
444
def show_form_dialog(self):
445
# Create form content
446
content = MDBoxLayout(
447
orientation="vertical",
448
spacing="16dp",
449
adaptive_height=True,
450
padding="16dp"
451
)
452
453
# Form fields
454
self.name_field = MDTextField(
455
hint_text="Enter name",
456
required=True,
457
mode="rectangle"
458
)
459
460
self.email_field = MDTextField(
461
hint_text="Enter email",
462
mode="rectangle"
463
)
464
465
content.add_widget(self.name_field)
466
content.add_widget(self.email_field)
467
468
# Dialog buttons
469
cancel_button = MDFlatButton(
470
text="CANCEL",
471
on_release=self.close_form_dialog
472
)
473
474
submit_button = MDRaisedButton(
475
text="SUBMIT",
476
on_release=self.submit_form
477
)
478
479
# Create dialog
480
self.form_dialog = MDDialog(
481
title="Add Contact",
482
type="custom",
483
content_cls=content,
484
buttons=[cancel_button, submit_button],
485
size_hint=(0.8, None),
486
height="300dp"
487
)
488
489
self.form_dialog.open()
490
491
def close_form_dialog(self, instance):
492
"""Close form dialog."""
493
self.form_dialog.dismiss()
494
495
def submit_form(self, instance):
496
"""Handle form submission."""
497
name = self.name_field.text
498
email = self.email_field.text
499
500
if name.strip():
501
print(f"Contact added: {name}, {email}")
502
self.form_dialog.dismiss()
503
self.show_snackbar("Contact added successfully")
504
else:
505
self.name_field.error = True
506
self.name_field.helper_text = "Name is required"
507
```
508
509
### Tooltip Usage
510
511
```python
512
from kivymd.uix.button import MDIconButton
513
from kivymd.uix.tooltip import MDTooltip
514
515
class TooltipButton(MDIconButton, MDTooltip):
516
"""Icon button with tooltip."""
517
pass
518
519
class MyApp(MDApp):
520
def build(self):
521
# Create button with tooltip
522
tooltip_button = TooltipButton(
523
icon="information",
524
tooltip_text="This button provides helpful information",
525
pos_hint={"center_x": 0.5, "center_y": 0.5}
526
)
527
528
return tooltip_button
529
```