New API: st.set_page_config

[akrolsmir]

Proposal

st.set_page_config(
	layout="centered",  # Can be "centered" or "wide". In the future also "dashboard", etc.
	initial_sidebar_state="auto",  # Can be "auto", "expanded", "collapsed"
	page_title=None,  # String or None. Strings get appended with "• Streamlit". 
	page_icon=None,  # String, anything supported by st.image, or None.
)

Background

We want to support the following in Streamlit:

1. Ability to set page favicon
2. Ability to set page title
3. Ability to make a page start in wide mode (today you need to toggle it in "preferences")
4. Ability to make a page start with the sidebar collapsed (today you need to collapse via the UI)

Must be first st command

For all of these settings, we'd prefer if the user sets them near the top of their script. Because it would be weird to have an app load, then show a bunch of stuff, and then change into wide mode, for example.

Immutable, for now

For title and favicon, it makes a lot of sense to support mutation. But it's not what 99% of the users will be doing, so it's OK if we don't support it at first.
For wide-mode and expand-sidebar, mutations make a lot less sense.

(Copied from our internal spec here)

[benlindsay]

@akrolsmir This sounds like a great solution, looking forward to it! One question I'm curious about is the difference between "auto" and "expanded" for the initial sidebar state. My impression is that in either case, if any st.sidebar.* functions have been called, the sidebar would show up expanded, and if no st.sidebar.* functions have been called, there will be no sidebar to expand or collapse. Is there something I'm missing?

[akrolsmir]

@benlindsay Thanks! "auto" and "expanded" will have different results depending on the width of the browser window. "auto" sidebar (aka today's behavior) starts expanded if the window is wider than a certain point, and starts collapsed otherwise. The two new options allow you to force the initial sidebar state one way or the other, ignoring browser width.

Incidentally, I'm wondering whether it makes sense to show an empty sidebar when initial_sidebar_state="expanded". I can imagine that somebody might want to dynamically append things to the sidebar and thus leave an open canvas there? But it's a pretty weird/niche use case, and it's already possible with st.sidebar.empty(). Will do some more product thinking here.

(in favor of showing the expanded empty sidebar: I don't think Streamlit is currently capable of looking forward through the app to detect whether there's an st.sidebar somewhere later, so as soon as st.set_page_config is called we'd need to make a decision)

[benlindsay]

Oh, duh, forgot about the screen size thing! Sounds great 🙂

[benlindsay]

Hi @akrolsmir, thanks for putting this together! I'd love to test this out, but it looks like the latest available nightly release was from August 5th. Any idea when this feature will come out in a nightly release?

[ZupoLlask]

Hi @akrolsmir,

I'm using latest nightly. Although st.beta_set_page_config() is the first streamlit call, sometimes (not always) when I hit a st.button() I'm getting the error below.

StreamlitAPIException: beta_set_page_config() can only be called once per app, and must be called as the first Streamlit command in your script.

For now, I'll try to avoid this error with a try/except...

[karriebear]

Hi @benlindsay, sorry we had some issues with the nightly over the past weekend but we just shipped out a release yesterday so you should be able to use this feature if you upgrade to the latest Streamlit version(0.65)!

[evavanrooijen]

For anybody who arrived here and is looking for the fix:

streamlit.set_page_config(page_title=None, page_icon=None, layout='centered', initial_sidebar_state='auto')

Configures the default settings of the page.
Note: This must be the first Streamlit command used in your app, and must only be set once.
Parameters
• page_title (str or None) – The page title, shown in the browser tab. If None,
defaults to the filename of the script (“app.py” would show “app • Streamlit”).
• page_icon (Anything supported by st.image or str or None) – The
page favicon. Besides the types supported by st.image (like URLs or numpy arrays), you
can pass in an emoji as a string (“”) or a shortcode (“:shark:”). If you’re feeling lucky,
try “random” for a random emoji! Emoji icons are courtesy of Twemoji and loaded from
MaxCDN.
• layout ("centered" or "wide") – How the page content should be laid out. Defaults to “centered”, which constrains the elements into a centered column of fixed width;
“wide” uses the entire screen.
• initial_sidebar_state ("auto" or "expanded" or "collapsed") –
How the sidebar should start out. Defaults to “auto”, which hides the sidebar on mobilesized devices, and shows it otherwise. “expanded” shows the sidebar initially; “collapsed”
hides it.