Check out our tutorial to learn about building custom, dynamic menus with st.page_link.

Display a link to another page in a multipage app or to an external page.

If another page in a multipage app is specified, clicking st.page_link stops the current page execution and runs the specified page as if the user clicked on it in the sidebar navigation.

If an external page is specified, clicking st.page_link opens a new tab to the specified page. The current script run will continue if not complete.

Function signature[source]

st.page_link(page, *, label=None, icon=None, help=None, disabled=False, use_container_width=None)


page (str)

The file path (relative to the main script) of the page to switch to. Alternatively, this can be the URL to an external page (must start with "http://" or "https://").

label (str)

The label for the page link. Labels are required for external pages. Labels can optionally contain Markdown and supports the following elements: Bold, Italics, Strikethroughs, Inline Code, and Emojis.

This also supports:

  • Emoji shortcodes, such as :+1: and :sunglasses:. For a list of all supported codes, see
  • LaTeX expressions, by wrapping them in "$" or "$$" (the "$$" must be on their own lines). Supported LaTeX functions are listed at
  • Colored text and background colors for text, using the syntax :color[text to be colored] and :color-background[text to be colored], respectively. color must be replaced with any of the following supported colors: blue, green, orange, red, violet, gray/grey, rainbow. For example, you can use :orange[your text here] or :blue-background[your text here].

Unsupported elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g. 1\. Not an ordered list.

icon (str, None)

An optional emoji or icon to display next to the button label. If icon is None (default), no icon is displayed. If icon is a string, the following options are valid:

  • A single-character emoji. For example, you can set icon="🚨" or icon="πŸ”₯". Emoji short codes are not supported.

  • An icon from the Material Symbols library (outlined style) in the format ":material/icon_name:" where "icon_name" is the name of the icon in snake case.

    For example, icon=":material/thumb_up:" will display the Thumb Up icon. Find additional icons in the Material Symbols font library.

help (str)

An optional tooltip that gets displayed when the link is hovered over.

disabled (bool)

An optional boolean, which disables the page link if set to True. The default is False.

use_container_width (bool)

An optional boolean, which makes the link stretch its width to match the parent container. The default is True for page links in the sidebar, and False for those in the main app.


Consider the following example given this file structure:

β”œβ”€β”€ pages/
β”‚   β”œβ”€β”€
β”‚   └──
import streamlit as st

st.page_link("", label="Home", icon="🏠")
st.page_link("pages/", label="Page 1", icon="1️⃣")
st.page_link("pages/", label="Page 2", icon="2️⃣", disabled=True)
st.page_link("", label="Google", icon="🌎")

The default navigation is shown here for comparison, but you can hide the default navigation using the client.showSidebarNavigation configuration option. This allows you to create custom, dynamic navigation menus for your apps!


Still have questions?

Our forums are full of helpful information and Streamlit experts.