0
# Navigation and Pages
1

2
Multi-page application support, navigation controls, and execution flow management. Streamlit provides comprehensive tools for building sophisticated multi-page applications with navigation, routing, and execution control.
3

4
## Capabilities
5

6
### Page Configuration
7

8
Configure page-level settings and metadata for your Streamlit application.
9

10
```python { .api }
11
def set_page_config(page_title=None, page_icon=None, layout="centered", initial_sidebar_state="auto", menu_items=None):
12
    """
13
    Configure page settings and metadata. Must be called at the very beginning of the script.
14

15
    Args:
16
        page_title (str, optional): Page title shown in browser tab
17
        page_icon (str, optional): Page icon (emoji or URL) shown in browser tab
18
        layout (str): Page layout ("centered" or "wide")
19
        initial_sidebar_state (str): Initial sidebar state ("auto", "expanded", "collapsed")
20
        menu_items (dict, optional): Custom menu items configuration
21

22
    Note:
23
        Must be the first Streamlit command in your script
24
    """
25
```
26

27
Example usage:
28
```python
29
st.set_page_config(
30
    page_title="My Dashboard",
31
    page_icon="📊",
32
    layout="wide",
33
    initial_sidebar_state="expanded",
34
    menu_items={
35
        "About": "This is my awesome dashboard!",
36
        "Report a bug": "mailto:support@example.com",
37
        "Get help": "https://docs.streamlit.io"
38
    }
39
)
40
```
41

42
### Multi-Page Navigation
43

44
Create and manage multi-page applications with structured navigation.
45

46
```python { .api }
47
def navigation(pages, *, position="sidebar", expanded=True):
48
    """
49
    Define application navigation structure with multiple pages.
50

51
    Args:
52
        pages (list): List of Page objects or page configurations
53
        position (str): Navigation position ("sidebar" or "hidden")
54
        expanded (bool): Whether navigation starts expanded
55

56
    Returns:
57
        Page: Currently selected page object
58
    """
59

60
class Page:
61
    """
62
    Represents a single page in a multi-page application.
63

64
    Args:
65
        page (str or callable): Page file path or function
66
        title (str, optional): Page title for navigation
67
        icon (str, optional): Page icon (emoji or material icon name)
68
        url_path (str, optional): Custom URL path for the page
69
        default (bool): Whether this is the default page
70
    """
71

72
    def __init__(self, page, *, title=None, icon=None, url_path=None, default=False):
73
        pass
74
```
75

76
Example usage:
77
```python
78
# Define pages
79
home_page = st.Page("pages/home.py", title="Home", icon="🏠", default=True)
80
data_page = st.Page("pages/data.py", title="Data Analysis", icon="📊")
81
settings_page = st.Page("pages/settings.py", title="Settings", icon="⚙️")
82

83
# Create navigation
84
pg = st.navigation([home_page, data_page, settings_page])
85

86
# Run the selected page
87
pg.run()
88

89
# Advanced navigation with sections
90
pg = st.navigation({
91
    "Main": [
92
        st.Page("home.py", title="Dashboard", icon="📈"),
93
        st.Page("reports.py", title="Reports", icon="📋")
94
    ],
95
    "Admin": [
96
        st.Page("users.py", title="User Management", icon="👥"),
97
        st.Page("settings.py", title="System Settings", icon="⚙️")
98
    ]
99
})
100
```
101

102
### App Logo and Branding
103

104
Configure application logo and branding elements.
105

106
```python { .api }
107
def logo(image, *, link=None, icon_image=None):
108
    """
109
    Set the application logo displayed in the navigation area.
110

111
    Args:
112
        image (str or bytes): Logo image file path, URL, or image data
113
        link (str, optional): URL to navigate when logo is clicked
114
        icon_image (str or bytes, optional): Smaller icon version for mobile/compact view
115
    """
116
```
117

118
Example usage:
119
```python
120
# Set logo with link
121
st.logo("assets/company_logo.png", link="https://company.com")
122

123
# Logo with separate icon
124
st.logo(
125
    image="assets/logo_full.png",
126
    icon_image="assets/logo_icon.png",
127
    link="https://company.com"
128
)
129
```
130

131
### Page Navigation Control
132

133
Functions for programmatically controlling page navigation and routing.
134

135
```python { .api }
136
def switch_page(page):
137
    """
138
    Navigate to a different page programmatically.
139

140
    Args:
141
        page (str or Page): Page name, file path, or Page object to navigate to
142
    """
143
```
144

145
Example usage:
146
```python
147
# Navigate based on user action
148
if st.button("Go to Data Analysis"):
149
    st.switch_page("pages/data.py")
150

151
# Navigate based on conditions
152
if not user_authenticated:
153
    st.switch_page("pages/login.py")
154

155
# Navigate with Page object
156
if st.button("Go to Settings"):
157
    st.switch_page(settings_page)
158

159
# Conditional navigation
160
user_role = get_user_role()
161
if user_role == "admin":
162
    st.switch_page("pages/admin.py")
163
elif user_role == "user":
164
    st.switch_page("pages/dashboard.py")
165
```
166

167
### Execution Control
168

169
Control the execution flow of your Streamlit application.
170

171
```python { .api }
172
def rerun():
173
    """
174
    Immediately rerun the current script from the top.
175

176
    Useful for refreshing the app state or triggering updates.
177
    """
178

179
def stop():
180
    """
181
    Stop execution of the current script.
182

183
    Nothing after this command will be executed in the current run.
184
    """
185
```
186

187
Example usage:
188
```python
189
# Rerun after data update
190
if st.button("Refresh Data"):
191
    update_data()
192
    st.rerun()
193

194
# Stop execution based on condition
195
if not user_has_permission:
196
    st.error("Access denied")
197
    st.stop()
198

199
# Conditional execution
200
if data_needs_refresh():
201
    refresh_data()
202
    st.rerun()
203

204
# Stop with message
205
if not config_valid:
206
    st.error("Invalid configuration. Please check settings.")
207
    st.stop()
208

209
# The rest of the app continues here
210
st.write("Application content...")
211
```
212

213
### Multi-Page Application Patterns
214

215
#### File-Based Pages
216

217
```python
218
# main.py - Entry point
219
import streamlit as st
220

221
# Page configuration
222
st.set_page_config(
223
    page_title="Analytics Platform",
224
    page_icon="📊",
225
    layout="wide"
226
)
227

228
# Define pages
229
pages = [
230
    st.Page("pages/dashboard.py", title="Dashboard", icon="📈", default=True),
231
    st.Page("pages/data_upload.py", title="Data Upload", icon="📤"),
232
    st.Page("pages/analysis.py", title="Analysis", icon="🔍"),
233
    st.Page("pages/reports.py", title="Reports", icon="📋"),
234
    st.Page("pages/settings.py", title="Settings", icon="⚙️")
235
]
236

237
# Navigation
238
pg = st.navigation(pages)
239
pg.run()
240
```
241

242
#### Function-Based Pages
243

244
```python
245
def home_page():
246
    st.title("Welcome to My App")
247
    st.write("This is the home page")
248

249
    if st.button("Go to Data"):
250
        st.switch_page(data_page)
251

252
def data_page():
253
    st.title("Data Analysis")
254
    st.write("Analyze your data here")
255

256
    # Data analysis code
257
    if st.button("Generate Report"):
258
        st.switch_page(report_page)
259

260
def report_page():
261
    st.title("Reports")
262
    st.write("View generated reports")
263

264
# Create pages
265
home = st.Page(home_page, title="Home", icon="🏠")
266
data = st.Page(data_page, title="Data", icon="📊")
267
report = st.Page(report_page, title="Reports", icon="📋")
268

269
# Navigation
270
pg = st.navigation([home, data, report])
271
pg.run()
272
```
273

274
#### Conditional Navigation
275

276
```python
277
# Authentication-based navigation
278
def get_navigation():
279
    if not st.session_state.get("authenticated", False):
280
        return st.navigation([
281
            st.Page("login.py", title="Login", icon="🔐")
282
        ])
283

284
    user_role = st.session_state.get("user_role", "user")
285

286
    if user_role == "admin":
287
        return st.navigation({
288
            "Main": [
289
                st.Page("dashboard.py", title="Dashboard", icon="📊"),
290
                st.Page("analytics.py", title="Analytics", icon="📈")
291
            ],
292
            "Admin": [
293
                st.Page("users.py", title="User Management", icon="👥"),
294
                st.Page("system.py", title="System Settings", icon="⚙️")
295
            ]
296
        })
297
    else:
298
        return st.navigation([
299
            st.Page("dashboard.py", title="Dashboard", icon="📊"),
300
            st.Page("profile.py", title="My Profile", icon="👤")
301
        ])
302

303
# Use conditional navigation
304
pg = get_navigation()
305
pg.run()
306
```
307

308
#### URL-Based Routing
309

310
```python
311
# Custom URL routing with query parameters
312
def handle_routing():
313
    # Get page from URL
314
    page = st.query_params.get("page", "home")
315

316
    # Route to appropriate function
317
    if page == "home":
318
        show_home()
319
    elif page == "data":
320
        show_data_page()
321
    elif page == "settings":
322
        show_settings()
323
    else:
324
        show_404()
325

326
def navigate_to(page_name):
327
    """Navigate to page and update URL."""
328
    st.query_params["page"] = page_name
329
    st.rerun()
330

331
# Navigation menu
332
col1, col2, col3 = st.columns(3)
333
with col1:
334
    if st.button("Home"):
335
        navigate_to("home")
336
with col2:
337
    if st.button("Data"):
338
        navigate_to("data")
339
with col3:
340
    if st.button("Settings"):
341
        navigate_to("settings")
342

343
# Handle the routing
344
handle_routing()
345
```
346

347
#### State-Aware Navigation
348

349
```python
350
# Navigation that responds to application state
351
def get_current_page():
352
    # Determine page based on app state
353
    if "current_workflow" not in st.session_state:
354
        return "welcome"
355

356
    workflow_state = st.session_state.current_workflow
357

358
    if workflow_state == "data_loaded":
359
        return "analysis"
360
    elif workflow_state == "analysis_complete":
361
        return "results"
362
    else:
363
        return "data_upload"
364

365
def update_workflow_state(new_state):
366
    """Update workflow state and navigate."""
367
    st.session_state.current_workflow = new_state
368
    st.rerun()
369

370
# State-based page display
371
current_page = get_current_page()
372

373
if current_page == "welcome":
374
    st.title("Welcome")
375
    if st.button("Start Analysis"):
376
        update_workflow_state("ready")
377

378
elif current_page == "data_upload":
379
    st.title("Upload Data")
380
    uploaded_file = st.file_uploader("Choose file")
381
    if uploaded_file and st.button("Process"):
382
        # Process file
383
        update_workflow_state("data_loaded")
384

385
elif current_page == "analysis":
386
    st.title("Analysis")
387
    if st.button("Run Analysis"):
388
        # Run analysis
389
        update_workflow_state("analysis_complete")
390

391
elif current_page == "results":
392
    st.title("Results")
393
    st.write("Analysis complete!")
394
```
395

396
#### Navigation with Session State
397

398
```python
399
# Initialize navigation state
400
if "nav_history" not in st.session_state:
401
    st.session_state.nav_history = ["home"]
402
    st.session_state.current_page = "home"
403

404
def navigate_with_history(page):
405
    """Navigate to page and maintain history."""
406
    st.session_state.nav_history.append(page)
407
    st.session_state.current_page = page
408
    st.rerun()
409

410
def go_back():
411
    """Navigate back to previous page."""
412
    if len(st.session_state.nav_history) > 1:
413
        st.session_state.nav_history.pop()
414
        st.session_state.current_page = st.session_state.nav_history[-1]
415
        st.rerun()
416

417
# Navigation controls
418
col1, col2 = st.columns([1, 4])
419
with col1:
420
    if len(st.session_state.nav_history) > 1:
421
        if st.button("← Back"):
422
            go_back()
423

424
# Page content based on current page
425
current_page = st.session_state.current_page
426

427
if current_page == "home":
428
    st.title("Home")
429
    if st.button("Go to Settings"):
430
        navigate_with_history("settings")
431

432
elif current_page == "settings":
433
    st.title("Settings")
434
    if st.button("Go to Profile"):
435
        navigate_with_history("profile")
436
```