Show API reference for

st.switch_page

Programmatically switch the current page in a multipage app.

When st.switch_page is called, the current page execution stops and the specified page runs as if the user clicked on it in the navigation menu. The specified page must be recognized by Streamlit's multipage architecture. Arbitrary Python scripts and URLs can't be passed to st.switch_page.

Function signature[source]

st.switch_page(page, *, query_params=None)

Parameters

page (str, Path, or StreamlitPage)

The page to switch to. This can be one of the following values:

  • Path to a Python file: The path can be a string or pathlib.Path object. It can be absolute or relative to the entrypoint file. The Python file must be the source of a page in st.navigation.

    If you are using the pages/ directory instead of st.navigation, the Python file must be your entrypoint file or a file in the pages/ directory.

  • StreamlitPage: The source of the StreamlitPage and its url_path must match a page defined in st.navigation. The StreamlitPage must be internal and can't be defined by a URL. Use st.Page to create a StreamlitPage object.

To switch to a page defined by a callable, you must use a StreamlitPage object.

query_params (dict, list of tuples, or None)

Query parameters to apply when navigating to the target page. This can be a dictionary or an iterable of key-value tuples. Values can be strings or iterables of strings (for repeated keys). When this is None (default), all non-embed query parameters are cleared during navigation.

Examples

Example 1: Basic usage

The following example shows how to switch to a different page in a multipage app that uses the pages/ directory:

your-repository/
├── pages/
│   ├── page_1.py
│   └── page_2.py
└── your_app.py

import streamlit as st

if st.button("Home"):
    st.switch_page("your_app.py")
if st.button("Page 1"):
    st.switch_page("pages/page_1.py")
if st.button("Page 2"):
    st.switch_page("pages/page_2.py")
Built with Streamlit 🎈

Example 2: Passing query parameters

The following example shows how to pass query parameters when switching to a different page. This example uses st.navigation to create a multipage app.

your-repository/
├── page_2.py
└── your_app.py

import streamlit as st

def page_1():
    st.title("Page 1")
    if st.button("Switch to Page 2"):
        st.switch_page("page_2.py", query_params={"utm_source": "page_1"})

pg = st.navigation([page_1, "page_2.py"])
pg.run()
Built with Streamlit 🎈
arrow_backPrevious: st.page_linkarrow_forwardNext: Execution flow
forum

Still have questions?

Our forums are full of helpful information and Streamlit experts.