API reference
Place a navigation bar in your Streamlit app.
If there is no st.set_page_config command on the app page, st_navbar must be the first Streamlit command used, and must only be set once per page. If there is a st.set_page_config command, then st_navbar must be the second one, right after it.
pages : list of str
A list with the name of each page that will be displayed in the navigation bar.
selected : str or None, optional
The preselected page on first render. It can be a name from pages, the logo_page (when there is a logo) or None. Defaults to the logo_page value, if there is a logo. In case there is not one, defaults to the first page of the pages list. When set to None, it will initialize empty and return None until the user selects a page.
logo_path : str, optional
The absolute path to an SVG file for a logo. It will be shown on the left side of the navigation bar. Defaults to None, where no logo is displayed.
logo_page : str or None, default="Home"
The page value that will be returned when the logo is selected, if there is one. Defaults to "Home". For a non-clickable logo, set this to None.
urls : dict of {str : str}, optional
A dictionary with the page name as the key and an external URL as the value, both as strings. The page name must be contained in the pages list. The URL will open in a new window or tab. The default is None.
styles : dict of {str : dict of {str : str}}, optional
Apply CSS styles to desired targets, through a dictionary with the HTML tag or pseudo-class name as the key and another dictionary to style it as the value. In the second dictionary, the key-value pair is the name of a CSS property and the value it takes, both in string format. It accepts CSS variables to be passed as values. Defaults to None, where just the default style is applied.
The available HTML tags are: "nav", "div", "ul", "li", "a", "img" and "span". To better understand the structure, check the Document Object Model section.
The available pseudo-classes are: "active" and "hover", which direct the styling to the "span" tag. The menu and sidebar buttons are only styled by "hover" (if they are set to True in options). Currently, "hover" only accepts two CSS properties, they are: "color" and "background-color".
options : bool or dict of {str : bool}, default=True
Customize the navbar with options that can be toggled on or off. It accepts a dictionary with the option name as the key and a boolean as the value. The available options are: "show_menu", "show_sidebar", "hide_nav", "fix_shadow" and "use_padding". Check the Options section for a description of each one.
It is also possible to toggle all options to the same state. Simply pass True to options, which is the parameter default value, or False.
adjust : bool, default=True
When set to True (default), it overrides some Streamlit behaviors and makes a series of CSS adjustments to display the navbar correctly.
In most cases, the CSS adjustments do not interfere with the rest of the web app, however there could be some situations where this occurs. If this happens, or it is desired to disable all of them, pass False to adjust and, when necessary, make your own CSS adjustments with st.html.
If set to False, it will also disable all adjustments made by options, regardless of whether they are on or off.
key : str or int, optional
A string or integer to use as a unique key for the component. If this is omitted, a key will be generated for the widget based on its content. Multiple navbars of the same type may not share the same key.
page : str or None
The page selected by the user. If there has been no interaction yet, returns the preselected page or None.
To style the navigation bar, it is important to understand its Document Object Model (DOM). For example, if a navbar is created with pages=["Page one", "Page two"] and an SVG logo. On the frontend side, the component builds this DOM (simplified for readability):
<nav>
<div>
<ul>
<li>
<a>
<img src="svg_logo" img/>
</a>
</li>
<li>
<a>
<span>Page one</span>
</a>
</li>
<li>
<a>
<span>Page two</span>
</a>
</li>
</ul>
</div>
</nav>Notice that the "a" tag will style both the logo and the page name. However, the "img" tag is unique to the logo, just as "span" is to the page names.
The component accepts theme configuration options to be passed as CSS variables in the styles dictionary, for example:
styles = {
"nav": {
"background-color": "var(--primary-color)"
}
}The CSS variables that can be used are:
--primary-color
--background-color
--secondary-background-color
--text-color
--font
The default navbar, which can be seen in the basic example, has its HTML tags styled with the following CSS properties:
/* HTML tags */
* {
margin: 0;
padding: 0;
}
nav {
align-items: center;
background-color: var(--secondary-background-color);
display: flex;
font-family: var(--font);
height: 2.875rem;
justify-content: center;
padding-left: 2rem;
padding-right: 2rem;
}
div {
max-width: 43.75rem;
width: 100%;
}
ul {
display: flex;
justify-content: space-between;
width: 100%;
}
li {
align-items: center;
display: flex;
list-style: none;
}
a {
text-decoration: none;
}
img {
display: flex;
height: 1.875rem;
}
span {
color: var(--text-color);
display: block;
text-align: center;
}As for the pseudo-classes, they have a different internal implementation. But to understand their default style, think of it as this (simplified for readability):
/* Pseudo-classes */
span:active {
color: var(--text-color);
font-weight: bold;
}
span:hover {
background-color: transparent;
color: var(--text-color);
}These HTML tags and pseudo-classes styles can be overridden, by simply passing another value to the respective target and CSS property in the styles parameter.
A fundamental CSS property to adjust is the "max-width" for the "div" tag. Because it controls how much space the page names have between them. The default value is "43.75rem", which works well in most cases. But if the navbar has a large number of pages, or longer names, it might be necessary to increase the maximum width. Conversely, whenever the navbar has few pages or short names, this value may need to be reduced.
The available options and their descriptions are:
"show_menu"
Show Streamlit's menu button in the navbar. When toggled off it hides the button.
True
|
|
False
|
|
"show_sidebar"
Show Streamlit's sidebar button in the navbar. However, it is still needed to use st.sidebar in the app, in order for the sidebar button to properly appear. Just like Streamlit's default behavior. When toggled off it hides the button.
True
|
|
False
|
|
"hide_nav"
Hide the sidebar navigation widget that Streamlit creates for multipage apps. When toggled off it resumes Streamlit's default behavior and shows the widget.
True
|
|
False
|
|
"fix_shadow"
Fix the shadow of the expanded sidebar, showing it no matter the window width. It is useful when the navbar and the sidebar have the same background color, which they do by default, because the shadow makes it possible to differentiate between the two elements. When toggled off it assumes Streamlit's default behavior, where it applies the shadow only when the window width is below a certain threshold.
True
|
|
False
|
|
"use_padding"
Position the body of the app, in the y axis of the window, 6rem from the top (if the navbar has a default height). This is the default style used by Streamlit. When toggled off it removes this padding and positions the body right below the navbar.
True
|
|
False
|
|