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, using the syntax :color[text to be colored], where color needs to be replaced with any of the following supported colors: blue, green, orange, red, violet, gray/grey, rainbow.

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)

An optional argument that specifies an emoji to use as the icon for the link. Shortcodes are not allowed. Please use a single character instead. E.g. "๐Ÿšจ", "๐Ÿ”ฅ", "๐Ÿค–", etc. Defaults to None, which means no icon is displayed.

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.

Was this page helpful?

editEdit this page on GitHub