Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 38 ยท Layout and Navigation

Multipage Apps

Build multipage Streamlit apps with the pages folder or st.navigation and st.Page. Learn page links, switch_page, sections, shared state, URL paths and a clean project layout.

A single script is fine for a small tool, but real apps grow: a home page, a data explorer, a model page, a settings page. Putting everything in one file turns it into a long scroll of if branches. Streamlit supports multipage apps, where each page is its own script and the sidebar shows a navigation menu.

There are two ways to build one. The simple, file-based way uses a pages/ folder. The flexible, code-based way uses st.navigation and st.Page. This lesson covers both and the rules about sharing data between pages. As elsewhere, the Streamlit code is real and read-only, with the page described in words; runnable blocks imitate the router idea.

Method 1: the pages/ folder

Create a project like this:

TEXT
my_app/
โ”œโ”€โ”€ app.py                  # the main page
โ””โ”€โ”€ pages/
    โ”œโ”€โ”€ 1_Explorer.py
    โ”œโ”€โ”€ 2_Model.py
    โ””โ”€โ”€ 3_Settings.py

Run it with streamlit run app.py. Streamlit finds the pages/ folder next to the entry file and builds a menu: "app" (the entry script's name), "Explorer", "Model", "Settings". The rules:

  • The menu label comes from the file name: the number prefix only sets the order and is removed; underscores become spaces.
  • The URL is the file name without the number (for example /Explorer).
  • Each page is a normal Streamlit script, run top to bottom like any other.
  • Files not ending in .py, or starting with a dot or underscore, are ignored.

It is the quickest start, and adequate for small apps. The drawbacks: the order is tied to file names, there is no grouping into sections, and logic that must run on every page (login check, shared sidebar) has to be repeated or imported by hand.

Method 2: st.navigation and st.Page

With the newer API, your entry file is a router. It declares the pages, asks Streamlit which one is selected, and runs it. Pages can live anywhere and can be either script files or Python functions.

Python
# app.py: the entry file, run for EVERY page
import streamlit as st

st.set_page_config(page_title="Sales Hub", layout="wide")   # once, here

def home():
    st.title("Home")
    st.write("Welcome! Pick a page from the menu.")

pages = {
    "Overview": [
        st.Page(home, title="Home", icon=":material/home:", default=True),
        st.Page("views/explorer.py", title="Explorer", icon=":material/search:"),
    ],
    "Admin": [
        st.Page("views/settings.py", title="Settings", icon=":material/settings:"),
    ],
}

nav = st.navigation(pages)

with st.sidebar:
    st.caption("Sales Hub v1.0")          # shared by every page

nav.run()

The sidebar shows a menu with two groups: Overview (Home, Explorer) and Admin (Settings), each with its icon. The selected page appears in the main area. Clicking another entry runs app.py again from the top (the entry file is a router, so it runs every time) and the selected page's script runs when nav.run() is reached. The sidebar caption appears on every page because it is in the entry file.

Key points:

  • st.Page(source, title=, icon=, url_path=, default=): source is a file path (relative to the entry file) or a callable. Exactly one page may be default=True; with a single unmarked page, the first is the default.
  • st.navigation(pages) accepts a list (flat menu) or a dict (section title to list of pages). It returns the selected Page.
  • st.navigation(pages, position="top") puts the menu in a bar at the top of the page instead of the sidebar, and position="hidden" hides it so you can build your own with st.page_link.
  • Pages can be chosen dynamically by user role: build the pages list from st.session_state and show the Admin group only to admins. That controls what the menu shows, but it is not security by itself; protect sensitive data on the server too.
  • Put page scripts outside pages/ (here views/) in this mode; a pages/ folder next to the entry file is ignored once you call st.navigation.
flowchart TD
    A["Browser requests /explorer"] --> B["app.py runs (the router)"]
    B --> C["st.set_page_config<br/>shared sidebar, login check"]
    C --> D["st.navigation(pages)<br/>selects explorer"]
    D --> E["nav.run()<br/>runs views/explorer.py"]

The entry file always runs first; the chosen page runs inside it.

The router idea you can run (stand-in)

This block is not Streamlit. It models the same flow: a table of pages, a router that chooses one by its URL path, shared code that runs for every page, and a default page. It is the mental model for st.navigation.

Python Stand-in: a router with sections

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

For the last request the Admin group is not in the menu, so the page is not found. In real Streamlit, hiding a page this way keeps it from the menu and from navigation, but remember it is a convenience, not a security boundary.

Linking between pages

Python
st.page_link("views/explorer.py", label="Open the explorer", icon="๐Ÿ”Ž")
st.page_link("https://docs.streamlit.io", label="Docs")      # external link

if st.button("Go to settings"):
    st.switch_page("views/settings.py")

st.page_link draws a link that navigates without a full reload. st.switch_page jumps to a page from code, for example after a successful login or form submission. For both you can pass the file path used in your st.Page definition (or the st.Page object itself).

Sharing data between pages

All pages of one app run in the same session, so st.session_state is shared:

Python
# On the Explorer page
st.session_state["selected_region"] = st.selectbox("Region", ["North", "South"])

# On another page
st.write("You chose", st.session_state.get("selected_region", "nothing yet"))

There is one gotcha. A widget's value is stored in session state under its key only while the widget is on the page. When the user navigates away, Streamlit forgets the widget's value, and the widget shows its default when they return. To keep a choice across pages, copy it to a normal session-state key you control, as above, and initialize the widget from it (index=... or value=st.session_state.get(...)). The State and Caching chapter covers this in more detail.

Data loaded once with @st.cache_data is shared by all pages and all users, so load shared data in a helper module rather than in each page.

A tidy project layout

TEXT
sales_hub/
โ”œโ”€โ”€ app.py                 # router + shared setup
โ”œโ”€โ”€ views/
โ”‚   โ”œโ”€โ”€ explorer.py
โ”‚   โ””โ”€โ”€ settings.py
โ”œโ”€โ”€ utils/
โ”‚   โ”œโ”€โ”€ data.py            # cached loading functions
โ”‚   โ””โ”€โ”€ charts.py          # functions returning figures
โ”œโ”€โ”€ .streamlit/
โ”‚   โ””โ”€โ”€ config.toml
โ””โ”€โ”€ requirements.txt

Page scripts stay short because loading and drawing logic live in utils/, which pages import like any module. Because Streamlit adds the entry file's folder to the import path, from utils.data import load_sales works from any page.

Two ways to build pages

pages folder Zero code, file names
st.navigation Router in app.py

Use navigation for anything beyond a toy.

1 / 2

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a pages/ folder app, how is the menu label for '2_Model.py' made?

    The prefix orders pages and is dropped; underscores become spaces.
  2. 2. With st.navigation, which file runs on every page view?

    The entry file acts as the router and always runs first.
  3. 3. What does st.switch_page do?

    It navigates programmatically, for example after a login.
  4. 4. You select a region on page A and leave. Why might the widget be reset when you return?

    Widget state is dropped when the widget is not rendered. Copy the value into your own session-state key to keep it.

Summary

  • A pages/ folder gives a quick multipage app; st.navigation with st.Page gives sections, icons, dynamic menus and a shared entry file.
  • The entry file runs on every page view: put set_page_config and shared sidebar code there.
  • Link with st.page_link and move with st.switch_page.
  • Pages share st.session_state, but widget values vanish when their widget is not shown, so store what matters under your own keys.
  • Move loading and drawing code into modules so page scripts stay short.

Next: How Streamlit Reruns Your Script