Streamlit Multi-Page Apps

The Folder Structure

The simplest multi-page app has this layout:

my-app/
├── app.py                 # Home page
├── pages/
│   ├── 1_Dashboard.py
│   ├── 2_Settings.py
│   └── 3_Reports.py
├── requirements.txt
└── .streamlit/
    └── secrets.toml

Key rules:

• The pages/ folder must be next to app.py.
• Number prefixes (1_, 2_) control the order in the sidebar.
• Underscores in filenames become spaces in the sidebar.
• Emojis in filenames become page icons.

Your Home Page (app.py)

import streamlit as st

st.set_page_config(
    page_title="My App",
    page_icon="🏠",
    layout="wide"
)

st.title("🏠 Home")
st.write("Welcome to my multi-page Streamlit app.")

st.page_link("pages/1_Dashboard.py", label="Go to Dashboard", icon="📊")
st.page_link("pages/2_Settings.py", label="Open Settings", icon="⚙️")

The st.page_link creates internal navigation buttons — great for landing pages.

Your First Sub-Page

Create pages/1_Dashboard.py:

import streamlit as st
import pandas as pd
import numpy as np

st.set_page_config(page_title="Dashboard", page_icon="📊")

st.title("📊 Dashboard")
st.write("This is the dashboard page.")

# Sample data
df = pd.DataFrame(
    np.random.randn(20, 3),
    columns=["Sales", "Users", "Revenue"]
)

st.line_chart(df)
st.dataframe(df)

That's it. Streamlit auto-detects the page and adds it to the sidebar.

Sharing State Across Pages

Use st.session_state to keep data between pages:

# pages/1_Dashboard.py
if "user" not in st.session_state:
    st.session_state.user = {"name": "Alice"}

st.write(f"Welcome, {st.session_state.user['name']}")

# pages/2_Settings.py
st.write(f"Editing settings for {st.session_state.user['name']}")

if st.button("Rename to Bob"):
    st.session_state.user["name"] = "Bob"
    st.success("Updated!")

Programmatic Navigation with st.navigation

For full control over the sidebar — grouping, hiding pages based on login, custom order — use st.navigation:

import streamlit as st

st.set_page_config(page_title="My App")

# Define pages programmatically
home = st.Page("app_pages/home.py", title="Home", icon="🏠", default=True)
dash = st.Page("app_pages/dashboard.py", title="Dashboard", icon="📊")
admin = st.Page("app_pages/admin.py", title="Admin", icon="🔒")

# Group them
pages = {
    "Main": [home, dash],
    "Admin": [admin] if st.session_state.get("is_admin") else [],
}

# Run navigation
pg = st.navigation(pages)
pg.run()

The advantage: you control visibility based on authentication. Non-admin users never see the Admin page.

Real-World Example: AI Chatbot with Pages

Here's how to structure a chatbot with a chat page, history page, and settings:

ai-app/
├── app.py                    # Home / landing
├── pages/
│   ├── 1_Chat.py            # Chat interface
│   ├── 2_History.py         # Saved conversations
│   └── 3_Settings.py        # API keys, model picker
└── utils/
    ├── openai_client.py
    └── storage.py

Each page imports from utils/, keeping the code DRY. The chat state lives in st.session_state.

👉 Read our Streamlit AI Chatbot Tutorial.