0
# Navigation Components
1

2
Navigation and breadcrumb components with Bootstrap styling, supporting badges, active state management, and flexible link generation for creating consistent navigation elements.
3

4
## Capabilities
5

6
### Navigation Items
7

8
Render navigation items with Bootstrap styling and optional badge indicators.
9

10
```python { .api }
11
def render_nav_item(endpoint, text, _badge='', _use_li=False, _badge_classes=''):
12
    """
13
    Render a navigation item with Bootstrap styling.
14
    
15
    Args:
16
        endpoint (str): Flask endpoint name for URL generation
17
        text (str): Display text for the navigation item
18
        _badge (str): Optional badge text to display
19
        _use_li (bool): Wrap in <li> element for nav lists
20
        _badge_classes (str): CSS classes for badge styling
21
        
22
    Returns:
23
        Rendered HTML navigation item with optional badge
24
        
25
    Bootstrap Versions:
26
        - Bootstrap 4: Uses 'badge badge-light' default classes
27
        - Bootstrap 5: Uses 'badge text-bg-light' default classes
28
        
29
    Active State:
30
        - Automatically adds 'active' class if current endpoint matches
31
        - Uses Flask's request.endpoint for comparison
32
    """
33
```
34

35
### Breadcrumb Items
36

37
Render individual breadcrumb navigation items for hierarchical navigation.
38

39
```python { .api }
40
def render_breadcrumb_item(endpoint, text):
41
    """
42
    Render a breadcrumb navigation item.
43
    
44
    Args:
45
        endpoint (str): Flask endpoint name for URL generation
46
        text (str): Display text for the breadcrumb item
47
        
48
    Returns:
49
        Rendered HTML breadcrumb item
50
        
51
    Usage:
52
        - Used within Bootstrap breadcrumb navigation
53
        - Automatically handles active state for current page
54
        - Generates proper Bootstrap breadcrumb markup
55
    """
56
```
57

58
## Navigation Patterns
59

60
### Basic Navigation Links
61

62
Simple navigation links without list wrappers:
63

64
```html
65
{% from 'bootstrap5/nav.html' import render_nav_item %}
66

67
<nav class="navbar navbar-expand-lg navbar-light bg-light">
68
    <div class="container">
69
        <a class="navbar-brand" href="/">My App</a>
70
        <div class="navbar-nav">
71
            {{ render_nav_item('home', 'Home') }}
72
            {{ render_nav_item('about', 'About') }}
73
            {{ render_nav_item('contact', 'Contact') }}
74
        </div>
75
    </div>
76
</nav>
77
```
78

79
### Navigation Lists
80

81
Navigation items wrapped in list elements:
82

83
```html
84
<ul class="nav nav-tabs">
85
    {{ render_nav_item('dashboard', 'Dashboard', _use_li=True) }}
86
    {{ render_nav_item('users', 'Users', _use_li=True) }}  
87
    {{ render_nav_item('settings', 'Settings', _use_li=True) }}
88
</ul>
89
```
90

91
### Navigation with Badges
92

93
Navigation items displaying badge indicators:
94

95
```html
96
<nav class="nav nav-pills flex-column">
97
    {{ render_nav_item('messages', 'Messages', _badge='5', _badge_classes='badge bg-primary') }}
98
    {{ render_nav_item('notifications', 'Notifications', _badge='12', _badge_classes='badge bg-warning') }}
99
    {{ render_nav_item('tasks', 'Tasks', _badge='new', _badge_classes='badge bg-success') }}
100
</nav>
101
```
102

103
### Breadcrumb Navigation
104

105
Hierarchical breadcrumb navigation:
106

107
```html
108
{% from 'base/nav.html' import render_breadcrumb_item %}
109

110
<nav aria-label="breadcrumb">
111
    <ol class="breadcrumb">
112
        <li class="breadcrumb-item">
113
            {{ render_breadcrumb_item('home', 'Home') }}
114
        </li>
115
        <li class="breadcrumb-item">
116
            {{ render_breadcrumb_item('admin', 'Admin') }}
117
        </li>
118
        <li class="breadcrumb-item">
119
            {{ render_breadcrumb_item('users', 'Users') }}
120
        </li>
121
        <li class="breadcrumb-item active" aria-current="page">
122
            Edit User
123
        </li>
124
    </ol>
125
</nav>
126
```
127

128
## Usage Examples
129

130
### Responsive Navigation Bar
131

132
```html
133
{% from 'bootstrap5/nav.html' import render_nav_item %}
134

135
<nav class="navbar navbar-expand-lg navbar-dark bg-primary">
136
    <div class="container">
137
        <a class="navbar-brand" href="{{ url_for('home') }}">My App</a>
138
        
139
        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" 
140
                data-bs-target="#navbarNav">
141
            <span class="navbar-toggler-icon"></span>
142
        </button>
143
        
144
        <div class="collapse navbar-collapse" id="navbarNav">
145
            <div class="navbar-nav me-auto">
146
                {{ render_nav_item('home', 'Home') }}
147
                {{ render_nav_item('products', 'Products') }}
148
                {{ render_nav_item('services', 'Services') }}
149
                {{ render_nav_item('contact', 'Contact') }}
150
            </div>
151
            
152
            <div class="navbar-nav">
153
                {% if current_user.is_authenticated %}
154
                    {{ render_nav_item('profile', 'Profile') }}
155
                    {{ render_nav_item('logout', 'Logout') }}
156
                {% else %}
157
                    {{ render_nav_item('login', 'Login') }}
158
                    {{ render_nav_item('register', 'Register') }}
159
                {% endif %}
160
            </div>
161
        </div>
162
    </div>
163
</nav>
164
```
165

166
### Admin Sidebar Navigation
167

168
```html
169
<div class="d-flex">
170
    <nav class="bg-light sidebar">
171
        <div class="nav flex-column">
172
            <h6 class="nav-header">Dashboard</h6>
173
            {{ render_nav_item('admin.dashboard', 'Overview') }}
174
            {{ render_nav_item('admin.analytics', 'Analytics') }}
175
            
176
            <h6 class="nav-header">Management</h6>
177
            {{ render_nav_item('admin.users', 'Users', _badge=user_count) }}
178
            {{ render_nav_item('admin.orders', 'Orders', _badge=pending_orders, 
179
                              _badge_classes='badge bg-warning') }}
180
            {{ render_nav_item('admin.products', 'Products') }}
181
            
182
            <h6 class="nav-header">Settings</h6>
183
            {{ render_nav_item('admin.config', 'Configuration') }}
184
            {{ render_nav_item('admin.logs', 'System Logs') }}
185
        </div>
186
    </nav>
187
    
188
    <main class="flex-grow-1 p-4">
189
        <!-- Main content -->
190
    </main>
191
</div>
192
```
193

194
### Tab Navigation
195

196
```html
197
<ul class="nav nav-tabs mb-3">
198
    {{ render_nav_item('user.profile', 'Profile', _use_li=True) }}
199
    {{ render_nav_item('user.settings', 'Settings', _use_li=True) }}
200
    {{ render_nav_item('user.security', 'Security', _use_li=True) }}
201
    {{ render_nav_item('user.billing', 'Billing', _use_li=True) }}
202
</ul>
203

204
<div class="tab-content">
205
    <!-- Tab content here -->
206
</div>
207
```
208

209
### Pill Navigation with Badges
210

211
```html
212
<nav class="nav nav-pills nav-justified">
213
    {{ render_nav_item('inbox', 'Inbox', _badge='15', _badge_classes='badge bg-primary ms-1') }}
214
    {{ render_nav_item('sent', 'Sent') }}
215
    {{ render_nav_item('drafts', 'Drafts', _badge='3', _badge_classes='badge bg-secondary ms-1') }}
216
    {{ render_nav_item('trash', 'Trash') }}
217
</nav>
218
```
219

220
### Multi-Level Breadcrumbs
221

222
```html
223
{% from 'base/nav.html' import render_breadcrumb_item %}
224

225
<nav aria-label="breadcrumb">
226
    <ol class="breadcrumb">
227
        <li class="breadcrumb-item">
228
            {{ render_breadcrumb_item('home', 'Home') }}
229
        </li>
230
        <li class="breadcrumb-item">
231
            {{ render_breadcrumb_item('blog', 'Blog') }}
232
        </li>
233
        <li class="breadcrumb-item">
234
            {{ render_breadcrumb_item('blog.category', 'Technology', category='tech') }}
235
        </li>
236
        <li class="breadcrumb-item active" aria-current="page">
237
            {{ post.title }}
238
        </li>
239
    </ol>
240
</nav>
241
```
242

243
### Bootstrap 4 vs Bootstrap 5 Differences
244

245
#### Bootstrap 4 Navigation
246
```html
247
{% from 'bootstrap4/nav.html' import render_nav_item %}
248

249
<!-- Bootstrap 4 badge classes -->
250
{{ render_nav_item('messages', 'Messages', _badge='5', 
251
                  _badge_classes='badge badge-primary') }}
252
```
253

254
#### Bootstrap 5 Navigation  
255
```html
256
{% from 'bootstrap5/nav.html' import render_nav_item %}
257

258
<!-- Bootstrap 5 badge classes -->
259
{{ render_nav_item('messages', 'Messages', _badge='5',
260
                  _badge_classes='badge text-bg-primary') }}
261
```
262

263
### Conditional Navigation
264

265
```html
266
<!-- Show different navigation based on user role -->
267
{% if current_user.is_admin %}
268
    <div class="nav flex-column">
269
        {{ render_nav_item('admin.dashboard', 'Admin Dashboard') }}
270
        {{ render_nav_item('admin.users', 'Manage Users') }}
271
        {{ render_nav_item('admin.settings', 'System Settings') }}
272
    </div>
273
{% elif current_user.is_authenticated %}
274
    <div class="nav flex-column">
275
        {{ render_nav_item('user.dashboard', 'My Dashboard') }}
276
        {{ render_nav_item('user.profile', 'My Profile') }}
277
        {{ render_nav_item('user.orders', 'My Orders') }}
278
    </div>
279
{% else %}
280
    <div class="nav flex-column">
281
        {{ render_nav_item('home', 'Home') }}
282
        {{ render_nav_item('about', 'About') }}
283
        {{ render_nav_item('login', 'Login') }}
284
    </div>
285
{% endif %}
286
```
287

288
### Dynamic Badge Content
289

290
```python
291
# View function
292
@app.route('/dashboard')
293
def dashboard():
294
    unread_messages = Message.query.filter_by(
295
        user_id=current_user.id, read=False
296
    ).count()
297
    
298
    pending_tasks = Task.query.filter_by(
299
        user_id=current_user.id, status='pending'
300
    ).count()
301
    
302
    return render_template('dashboard.html', 
303
                         unread_messages=unread_messages,
304
                         pending_tasks=pending_tasks)
305
```
306

307
```html
308
<!-- Template with dynamic badges -->
309
<nav class="nav nav-pills">
310
    {{ render_nav_item('messages', 'Messages', 
311
                      _badge=unread_messages if unread_messages > 0 else '',
312
                      _badge_classes='badge bg-danger') }}
313
    
314
    {{ render_nav_item('tasks', 'Tasks',
315
                      _badge=pending_tasks if pending_tasks > 0 else '',
316
                      _badge_classes='badge bg-warning') }}
317
</nav>
318
```
319

320
## Active State Management
321

322
Navigation components automatically handle active states:
323

324
1. **Endpoint Matching**: Compares current `request.endpoint` with nav item endpoint
325
2. **CSS Classes**: Adds `active` class to matching navigation items
326
3. **Accessibility**: Includes appropriate ARIA attributes for screen readers
327

328
```html
329
<!-- If current page is 'users' endpoint -->
330
{{ render_nav_item('users', 'Users') }}
331
<!-- Renders as: -->
332
<a class="nav-link active" href="/users">Users</a>
333

334
<!-- Other endpoints render without active class -->
335
{{ render_nav_item('settings', 'Settings') }}
336
<!-- Renders as: -->
337
<a class="nav-link" href="/settings">Settings</a>
338
```