0
# Navigation Components
1
2
Navigation components that implement Material Design navigation patterns including app bars, navigation drawers, bottom navigation, tabs, and navigation rails. These components provide consistent navigation experiences across different screen sizes and device types.
3
4
## Capabilities
5
6
### App Bars
7
8
Top and bottom app bars that provide primary navigation and actions for screens.
9
10
```python { .api }
11
class MDTopAppBar:
12
"""
13
Material Design top app bar.
14
15
Primary app bar positioned at the top of the screen containing
16
title, navigation actions, and overflow menu.
17
"""
18
title: str # App bar title text
19
anchor_title: str # Title anchor: "left", "center", "right"
20
21
# Action items
22
left_action_items: list # Left action buttons: [["icon", callback], ...]
23
right_action_items: list # Right action buttons: [["icon", callback], ...]
24
25
# Visual styling
26
md_bg_color: str | list # Background color
27
specific_text_color: str | list # Title text color
28
elevation: float # App bar elevation
29
30
# Navigation
31
type: str # App bar type: "top" or "bottom"
32
33
def set_left_action_items(self, items: list):
34
"""
35
Set left action items.
36
37
Args:
38
items (list): List of [icon, callback] pairs
39
"""
40
41
def set_right_action_items(self, items: list):
42
"""
43
Set right action items.
44
45
Args:
46
items (list): List of [icon, callback] pairs
47
"""
48
49
class MDBottomAppBar:
50
"""
51
Material Design bottom app bar.
52
53
App bar positioned at the bottom of the screen, often used with
54
floating action buttons and navigation actions.
55
"""
56
md_bg_color: str | list # Background color
57
elevation: float # App bar elevation
58
59
# Action items
60
left_action_items: list # Left action buttons
61
right_action_items: list # Right action buttons
62
63
# FAB integration
64
allow_hidden: bool # Allow hiding on scroll
65
```
66
67
### Navigation Drawer
68
69
Slide-out navigation panel for primary navigation destinations.
70
71
```python { .api }
72
class MDNavigationLayout:
73
"""
74
Navigation layout container for drawer implementations.
75
76
Container that manages the relationship between content and navigation drawer.
77
"""
78
79
class MDNavigationDrawer:
80
"""
81
Material Design navigation drawer.
82
83
Slide-out panel containing navigation destinations and actions.
84
"""
85
type: str # Drawer type: "standard" or "modal"
86
anchor: str # Drawer anchor: "left" or "right"
87
close_on_click: bool # Close drawer when item clicked
88
state: str # Drawer state: "close" or "open"
89
90
# Visual styling
91
drawer_logo: str # Logo image source
92
drawer_header_text: str # Header text
93
94
# Behavior
95
enable_swiping: bool # Enable swipe to open/close
96
swipe_distance: int # Swipe distance threshold
97
swipe_edge_width: int # Edge width for swipe detection
98
99
def set_state(self, state: str, animation: bool = True):
100
"""
101
Set drawer state.
102
103
Args:
104
state (str): "open" or "close"
105
animation (bool): Animate the transition
106
"""
107
108
class MDNavigationDrawerMenu:
109
"""
110
Navigation drawer menu container.
111
112
Container for organizing navigation drawer items.
113
"""
114
spacing: str | int # Spacing between menu items
115
116
class MDNavigationDrawerHeader:
117
"""
118
Navigation drawer header section.
119
120
Header area typically containing user info or app branding.
121
"""
122
text: str # Header text
123
source: str # Header image source
124
125
class MDNavigationDrawerLabel:
126
"""
127
Text label for navigation drawer sections.
128
129
Section divider with text label.
130
"""
131
text: str # Label text
132
theme_text_color: str # Text color theme
133
134
class MDNavigationDrawerDivider:
135
"""
136
Visual divider for navigation drawer sections.
137
138
Horizontal line divider between sections.
139
"""
140
141
class MDNavigationDrawerItem:
142
"""
143
Navigation drawer menu item.
144
145
Individual navigation item with icon, text, and action.
146
"""
147
text: str # Item text
148
icon: str # Item icon from md_icons
149
active: bool # Active/selected state
150
151
# Visual styling
152
text_color: str | list # Text color
153
icon_color: str | list # Icon color
154
selected_color: str | list # Selected state color
155
156
def on_release(self):
157
"""Called when item is pressed."""
158
```
159
160
### Navigation Rail
161
162
Vertical navigation component for larger screens and desktop applications.
163
164
```python { .api }
165
class MDNavigationRail:
166
"""
167
Material Design navigation rail.
168
169
Vertical navigation component positioned on the left side,
170
suitable for larger screens and desktop applications.
171
"""
172
type: str # Rail type: "unselected" or "selected"
173
anchor: str # Rail anchor: "left" or "right"
174
175
# Visual styling
176
md_bg_color: str | list # Background color
177
elevation: float # Rail elevation
178
179
# Items
180
selected_color_background: str | list # Selected item background
181
ripple_color_item: str | list # Item ripple color
182
183
class MDNavigationRailItem:
184
"""
185
Navigation rail menu item.
186
187
Individual item in the navigation rail with icon and optional text.
188
"""
189
text: str # Item text (optional)
190
icon: str # Item icon from md_icons
191
active: bool # Active/selected state
192
193
def on_release(self):
194
"""Called when item is pressed."""
195
196
class MDNavigationRailFabButton:
197
"""
198
Floating action button for navigation rail.
199
200
FAB integrated into the navigation rail layout.
201
"""
202
icon: str # FAB icon
203
md_bg_color: str | list # Background color
204
205
class MDNavigationRailMenuButton:
206
"""
207
Menu button for navigation rail.
208
209
Button that triggers navigation rail menu or drawer.
210
"""
211
icon: str # Menu icon (typically "menu")
212
```
213
214
### Bottom Navigation
215
216
Bottom navigation bar for primary navigation destinations on mobile.
217
218
```python { .api }
219
class MDBottomNavigation:
220
"""
221
Material Design bottom navigation.
222
223
Bottom navigation bar with multiple tabs for primary navigation
224
destinations, typically used on mobile devices.
225
"""
226
panel_color: str | list # Background color
227
selected_color_background: str | list # Selected tab background
228
text_color_active: str | list # Active text color
229
text_color_normal: str | list # Normal text color
230
231
# Behavior
232
use_text: bool # Show text labels
233
previous_tab: object # Reference to previous tab
234
235
def switch_tab(self, name_tab: str):
236
"""
237
Switch to specified tab.
238
239
Args:
240
name_tab (str): Name of tab to switch to
241
"""
242
243
class MDBottomNavigationItem:
244
"""
245
Bottom navigation tab item.
246
247
Individual tab in bottom navigation with icon, text, and content.
248
"""
249
name: str # Tab name (unique identifier)
250
text: str # Tab label text
251
icon: str # Tab icon from md_icons
252
253
# Content
254
# Add widgets to this item to display when tab is active
255
256
def on_tab_press(self):
257
"""Called when tab is pressed."""
258
```
259
260
### Tabs
261
262
Horizontal tab navigation for organizing content into sections.
263
264
```python { .api }
265
class MDTabs:
266
"""
267
Material Design tabs.
268
269
Horizontal tab navigation for organizing content into different
270
sections or views within the same context.
271
"""
272
# Tab behavior
273
tab_hint_x: bool # Enable tab width hints
274
tab_bar_height: str # Tab bar height (e.g., "48dp")
275
276
# Visual styling
277
indicator_color: str | list # Active tab indicator color
278
text_color_normal: str | list # Normal tab text color
279
text_color_active: str | list # Active tab text color
280
281
# Scrolling
282
scrollable: bool # Enable horizontal scrolling for many tabs
283
284
def add_widget(self, widget):
285
"""Add tab to the tabs widget."""
286
287
def switch_tab(self, name_tab: str):
288
"""
289
Switch to specified tab.
290
291
Args:
292
name_tab (str): Name of tab to switch to
293
"""
294
295
class MDTabsBase:
296
"""
297
Base class for tab content.
298
299
Base class that tab content widgets should inherit from.
300
"""
301
text: str # Tab title text
302
icon: str # Tab icon (optional)
303
304
class MDTabsLabel:
305
"""
306
Tab label component.
307
308
Text label component used within tabs.
309
"""
310
text: str # Label text
311
tab: object # Reference to parent tab
312
```
313
314
## Usage Examples
315
316
### Top App Bar with Actions
317
318
```python
319
from kivymd.uix.toolbar import MDTopAppBar
320
from kivymd.uix.screen import MDScreen
321
322
class MainScreen(MDScreen):
323
def build(self):
324
# Create app bar
325
app_bar = MDTopAppBar(
326
title="My App",
327
anchor_title="left",
328
elevation=4,
329
left_action_items=[["menu", self.open_nav_drawer]],
330
right_action_items=[
331
["search", self.open_search],
332
["dots-vertical", self.open_menu]
333
]
334
)
335
336
return app_bar
337
338
def open_nav_drawer(self, instance):
339
"""Open navigation drawer."""
340
print("Opening navigation drawer")
341
342
def open_search(self, instance):
343
"""Open search."""
344
print("Opening search")
345
346
def open_menu(self, instance):
347
"""Open overflow menu."""
348
print("Opening menu")
349
```
350
351
### Navigation Drawer
352
353
```python
354
from kivymd.uix.navigationdrawer import (
355
MDNavigationLayout, MDNavigationDrawer, MDNavigationDrawerMenu,
356
MDNavigationDrawerHeader, MDNavigationDrawerItem, MDNavigationDrawerDivider
357
)
358
from kivymd.uix.screen import MDScreen
359
360
class MainScreen(MDScreen):
361
def build(self):
362
# Create navigation layout
363
nav_layout = MDNavigationLayout()
364
365
# Create main content screen
366
content_screen = MDScreen()
367
368
# Create navigation drawer
369
nav_drawer = MDNavigationDrawer(
370
type="standard",
371
close_on_click=True
372
)
373
374
# Create drawer menu
375
menu = MDNavigationDrawerMenu()
376
377
# Add header
378
header = MDNavigationDrawerHeader(
379
text="My App",
380
source="logo.png"
381
)
382
menu.add_widget(header)
383
384
# Add menu items
385
menu_items = [
386
("home", "Home"),
387
("account", "Profile"),
388
("settings", "Settings"),
389
("help", "Help"),
390
("logout", "Logout")
391
]
392
393
for icon, text in menu_items:
394
if text == "Help":
395
menu.add_widget(MDNavigationDrawerDivider())
396
397
item = MDNavigationDrawerItem(
398
text=text,
399
icon=icon,
400
on_release=lambda x, item_text=text: self.nav_item_pressed(item_text)
401
)
402
menu.add_widget(item)
403
404
nav_drawer.add_widget(menu)
405
406
# Assemble layout
407
nav_layout.add_widget(content_screen)
408
nav_layout.add_widget(nav_drawer)
409
410
return nav_layout
411
412
def nav_item_pressed(self, item_text):
413
"""Handle navigation item press."""
414
print(f"Navigation item pressed: {item_text}")
415
```
416
417
### Bottom Navigation
418
419
```python
420
from kivymd.uix.bottomnavigation import MDBottomNavigation, MDBottomNavigationItem
421
from kivymd.uix.label import MDLabel
422
423
class MainApp(MDApp):
424
def build(self):
425
# Create bottom navigation
426
bottom_nav = MDBottomNavigation(
427
panel_color="primary",
428
selected_color_background="primary",
429
text_color_active="white"
430
)
431
432
# Home tab
433
home_tab = MDBottomNavigationItem(
434
name="home",
435
text="Home",
436
icon="home"
437
)
438
home_tab.add_widget(MDLabel(
439
text="Home Screen Content",
440
halign="center"
441
))
442
443
# Search tab
444
search_tab = MDBottomNavigationItem(
445
name="search",
446
text="Search",
447
icon="magnify"
448
)
449
search_tab.add_widget(MDLabel(
450
text="Search Screen Content",
451
halign="center"
452
))
453
454
# Profile tab
455
profile_tab = MDBottomNavigationItem(
456
name="profile",
457
text="Profile",
458
icon="account"
459
)
460
profile_tab.add_widget(MDLabel(
461
text="Profile Screen Content",
462
halign="center"
463
))
464
465
# Add tabs to navigation
466
bottom_nav.add_widget(home_tab)
467
bottom_nav.add_widget(search_tab)
468
bottom_nav.add_widget(profile_tab)
469
470
return bottom_nav
471
```
472
473
### Tabs with Content
474
475
```python
476
from kivymd.uix.tab import MDTabs, MDTabsBase
477
from kivymd.uix.label import MDLabel
478
from kivymd.uix.boxlayout import MDBoxLayout
479
480
class TabContent(MDTabsBase):
481
"""Custom tab content."""
482
483
def __init__(self, tab_text, content_text, **kwargs):
484
super().__init__(**kwargs)
485
self.text = tab_text
486
487
# Create content layout
488
layout = MDBoxLayout(
489
orientation="vertical",
490
adaptive_height=True,
491
spacing="16dp",
492
padding="16dp"
493
)
494
495
# Add content
496
label = MDLabel(
497
text=content_text,
498
theme_text_color="Primary",
499
halign="center"
500
)
501
502
layout.add_widget(label)
503
self.add_widget(layout)
504
505
class MainApp(MDApp):
506
def build(self):
507
# Create tabs
508
tabs = MDTabs(
509
tab_bar_height="48dp",
510
indicator_color="primary",
511
scrollable=True
512
)
513
514
# Add tab content
515
tab_data = [
516
("Overview", "Overview content goes here"),
517
("Details", "Detailed information content"),
518
("Reviews", "User reviews and ratings"),
519
("Related", "Related items and suggestions")
520
]
521
522
for tab_text, content_text in tab_data:
523
tab_content = TabContent(tab_text, content_text)
524
tabs.add_widget(tab_content)
525
526
return tabs
527
```
528
529
### Navigation Rail for Desktop
530
531
```python
532
from kivymd.uix.navigationrail import (
533
MDNavigationRail, MDNavigationRailItem,
534
MDNavigationRailFabButton
535
)
536
from kivymd.uix.boxlayout import MDBoxLayout
537
538
class DesktopLayout(MDBoxLayout):
539
def __init__(self, **kwargs):
540
super().__init__(**kwargs)
541
self.orientation = "horizontal"
542
543
# Create navigation rail
544
nav_rail = MDNavigationRail(
545
type="selected",
546
md_bg_color="primary",
547
elevation=2
548
)
549
550
# Add FAB to rail
551
fab = MDNavigationRailFabButton(
552
icon="plus",
553
md_bg_color="accent"
554
)
555
nav_rail.add_widget(fab)
556
557
# Add navigation items
558
nav_items = [
559
("home", "Home"),
560
("email", "Mail"),
561
("calendar", "Calendar"),
562
("folder", "Files"),
563
("settings", "Settings")
564
]
565
566
for icon, text in nav_items:
567
item = MDNavigationRailItem(
568
text=text,
569
icon=icon,
570
on_release=lambda x, item_text=text: self.rail_item_pressed(item_text)
571
)
572
nav_rail.add_widget(item)
573
574
# Content area
575
content_area = MDBoxLayout(
576
md_bg_color="surface",
577
size_hint_x=0.8
578
)
579
580
# Add to main layout
581
self.add_widget(nav_rail)
582
self.add_widget(content_area)
583
584
def rail_item_pressed(self, item_text):
585
"""Handle rail item press."""
586
print(f"Rail item pressed: {item_text}")
587
```