Tech With Galvan
Back to Articles
DevelopmentAug 9, 2026 • 5 min read

Streamlit Multipage Apps: Structure, Navigation, and State

Build a multipage Streamlit app — file-based routing, shared state, navigation, and project structure for apps with more than one screen.

Galvan
Galvan

Founder & Creator

Introduction

Single-page Streamlit apps hit a wall around 200 lines: the UI becomes a wall of if/else blocks and the sidebar turns into a maze. Multipage apps fix this — one file per page, automatic navigation, and shared state across pages.

This post covers the modern (file-based) approach, introduced in Streamlit 1.16 and now the standard.

File structure

my_app/
├── Home.py                  # entry point (landing page)
├── pages/
│   ├── 1_Dashboard.py
│   ├── 2_Settings.py
│   └── 3_About.py
├── utils.py                 # shared helpers
├── .streamlit/
│   └── secrets.toml
└── requirements.txt

Streamlit auto-discovers pages/*.py and builds the sidebar navigation. The number prefix controls order.

Step 1: Home page (entry point)

# Home.py
import streamlit as st

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

st.title("🏠 Welcome")
st.write("Use the sidebar to navigate.")

# Shared state (persists across pages within a session)
if "counter" not in st.session_state:
    st.session_state.counter = 0

st.metric("Shared counter", st.session_state.counter)

Step 2: A page

# pages/1_Dashboard.py
import streamlit as st
import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from utils import load_data

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

st.title("📊 Dashboard")

# Read shared state
st.write(f"Counter from home: {st.session_state.get('counter', 0)}")

# Increment
if st.button("Increment"):
    st.session_state.counter = st.session_state.get("counter", 0) + 1
    st.rerun()

data = load_data()
st.dataframe(data)

Step 3: Shared helpers

# utils.py
import pandas as pd
import streamlit as st

@st.cache_data
def load_data():
    return pd.read_csv("data.csv")

def require_login():
    if not st.session_state.get("logged_in"):
        st.warning("Please log in first.")
        st.stop()

Import in any page with from utils import .... The sys.path trick above makes imports work regardless of how Streamlit launches the app.

Step 4: Page config per page

Each page can set its own title, icon, and layout:

st.set_page_config(
    page_title="Settings",
    page_icon="⚙️",
    layout="centered",        # or "wide"
    initial_sidebar_state="expanded",
)

Set this as the first Streamlit call on each page (before any other st.*).

Step 5: Hide pages conditionally

# pages/2_Admin.py
import streamlit as st

if not st.session_state.get("is_admin"):
    st.stop()   # page won't render; still shows in nav though

st.title("Admin panel")

To fully hide from the sidebar, use st.navigation (new in 1.36+):

# Home.py (entry point)
import streamlit as st

pages = [
    st.Page("Home.py", title="Home", icon="🏠"),
    st.Page("pages/1_Dashboard.py", title="Dashboard", icon="📊"),
]
if st.session_state.get("is_admin"):
    pages.append(st.Page("pages/2_Admin.py", title="Admin", icon="🔐"))

nav = st.navigation(pages)
nav.run()

st.navigation gives you full control over which pages appear and their order.

Step 6: Shared state patterns

Pattern A: session_state (in-memory, per-user)

# Set on one page
st.session_state.user = {"name": "Galvan", "role": "admin"}

# Read on another
user = st.session_state.get("user")

Persists across pages within the same browser session. Lost on tab close.

Pattern B: query params (URL state)

# Read from URL: ?tab=settings
params = st.query_params
tab = params.get("tab", "home")
st.query_params["tab"] = "settings"   # updates the URL

Good for shareable links and deep linking.

Pattern C: persistent (database)

For state that survives sessions, use Supabase or a file. Store a user ID in session_state, fetch their data from the DB on each page.

Step 7: Page groups (sections)

With st.navigation, group pages:

pages = {
    "Main": [
        st.Page("Home.py", title="Home", icon="🏠"),
        st.Page("pages/1_Dashboard.py", title="Dashboard", icon="📊"),
    ],
    "Account": [
        st.Page("pages/3_Settings.py", title="Settings", icon="⚙️"),
        st.Page("pages/4_Logout.py", title="Logout", icon="🚪"),
    ],
}
nav = st.navigation(pages)
nav.run()

Renders as grouped sections in the sidebar.

Common mistakes

  • Import errors — pages/*.py can’t import from the root by default. Add sys.path.insert(0, ...) or use a utils.py at the root with the path trick.
  • Multiple set_page_config — only the first call wins. Set it once per page, at the top.
  • State not shared — st.session_state IS shared across pages in the same session. If it’s not persisting, you’re probably using a local variable.
  • File naming — prefix with numbers for order (1_Dashboard.py). Streamlit sorts alphabetically.
  • Stale cache — @st.cache_data is global; clear it with .clear() when data changes.

Key Concepts

  • File-based routing = one file per page in pages/
  • st.navigation = programmatic page control (groups, conditional pages)
  • st.session_state = shared state across pages
  • st.query_params = URL state for deep linking
  • st.Page = page definition with title/icon

What to Try Next

  • Add auth and gate pages behind login.
  • Persist user data with Supabase.
  • Use st.navigation for a custom sidebar with user info.
  • Combine with caching for fast page loads.

FAQ

Streamlit multipage vs single file with tabs?

Multipage = separate URLs, better for distinct sections. Tabs = one page, better for related views. Use multipage for apps with 3+ distinct screens.

Can I have nested pages (sub-routes)?

Not natively. Flatten your structure: 1_Dashboard.py, 2_Dashboard_Detail.py. Or use query params for sub-views.

How do I deploy a multipage app?

Same as single-page: push to GitHub, deploy on Streamlit Cloud. The pages/ folder is auto-detected. No config needed.