All of us on the Streamlit Data Science team are massive Streamlit fans (obviously!). In our day jobs, we produce internal Streamlit apps. These apps do everything from helping our partners discover useful tables in our data warehouse, to graphing Streamlit Community Cloud’s monthly active developers over time, to seeing what Streamlit features are rising and falling in use. This means we produce a ton of apps and keep them all in one large, multi-page app.
But as we traveled down this path, we found ourselves in a bit of a pickle. We’d create a new app, find a widget combination that sheds light on something super useful, and would want to share it in that exact state. For example, what if we worked for Uber and wanted to share how NYC rideshare traffic looked at 2 am? Or how the 2 am traffic differed from the 2 pm traffic?
To do this, we could:
- Set the app's widgets' default values so that the user could find them on screen load. We'd share the app in this exact initial state, but the users can still interact with it and explore other configurations.
- Take app screenshots and send them via Slack, Notion, or email.
- Write instructions for rediscovering the finding, either in the app itself or in the message to users, “Hi! We made a new change in our NYC rideshare app. Here is the link. Go ahead and change the slider bar to 2am. We noticed an interesting concentration of rides in the Chelsea area during that time, especially relative to the 2pm time period.”
But these options aren’t all that great.
- Option 1 doesn’t take into consideration that we often have many cool findings per app! It also doesn’t work for our multi-page app setup, so it’s out of the picture.
- Option 2 defeats the purpose of an app. Why create an interactive app when users will see only a static photo?
- Option 3 puts in friction between the user and the insight. This creates a bad user experience.
We solved this by combining session state with passing the URL query parameters to Streamlit apps. In this post, I’ll walk you through a minimum viable app. You’ll learn:
- How to get URL query parameters into Streamlit
- How to use those parameters in Streamlit widgets
- How to sync widgets and your app’s URLs
How to get URL query parameters into Streamlit
This part is the easiest!
Streamlit has a feature called
st.experimental_get_query_parameters (read more about it in our docs). It returns a list of parameters that are already in the URL. For example, here is the URL of a locally deployed app http://localhost:8501/?my_name=tyler&month=may.
This URL has two parameters (
month) with values (
may). Or for an app deployed on Streamlit Community Cloud, the link https://share.streamlit.io/tylerjrichards/streamlit_goodreads_app/books.py/?is_checked=True has the parameter
is_checked with the value
This code pulls the parameters from the URL and prints them out:
import streamlit as st my_query_params = st.experimental_get_query_params() st.write("My Query Params:") st.write(my_query_params)
Now you can save this code in a Python file (mine is
streamlit_example_app.py), run it with
streamlit run streamlit_example_app.py , and get the URL parameters programmatically!
See how query parameters can be “passed” to your Streamlit app. 👆
NOTE: You probably noticed the
experimental_ prefix in our function call. That means it's a feature we're still working on or trying to understand, and it'll go through many iterations as we get feedback from the community. You can find more information about experimental features in our docs!
Now that you have the Streamlit URL parameters, you can use them to influence the Streamlit widgets we use in building apps.
For example, let’s create a URL parameter called
is_checked and pass it to the value of a Streamlit checkbox. We return the query parameters as lists inside a dictionary, so you can use the
get function to pull the parameter (if it exists), and use
== "true" to make it a boolean that is passed into your checkbox value parameter:
import streamlit as st query_params = st.experimental_get_query_params() my_checkbox = st.checkbox( "Example Checkbox", value=query_params.get("is_checked", ["False"]).lower() == "true", ) st.write(query_params)
Now if you go to http://localhost:8501/is_checked=True, you’ll see that the checkbox is checked:
See how the checkbox value equals the query parameter. 👆
This is a great V0!
But what if you want the URL to change when you change widget inputs? Typing out URL parameters is annoying. Instead, take advantage of
We have lots of great documentation on
st.session_state. Check it out if this is your first rodeo!
As a super basic introduction,
st.session_state is a magic dictionary that doesn’t get reset every time the page updates. Use it to see how users interact with your app across all reruns. And if you want to change your URL parameters, use
For this to work, you’ll need to ‘reset’ your URL parameter at the end of your app with
st.experimental_set_query_params and ensure you’re only reading from
st.experimental_get_query_params on the first app run.
To do this, check if the
is_check parameter is inside
st.session_state. If it’s not, add it to
st.session_state as we did above 👆 to get the current query parameters from your URL:
import streamlit as st query_params = st.experimental_get_query_params() if "is_checked" not in st.session_state: st.session_state["is_checked"] = ( query_params.get("is_checked", ["False"]).lower() == "true" ) my_checkbox = st.checkbox("Example Checkbox", key="is_checked") st.experimental_set_query_params(is_checked=my_checkbox) st.write(st.session_state)
You’ll notice another change in the code.
Before, you had to assign the default value of the checkbox. Now you can use the key parameter to keep the checkbox synced with
is_checked from inside
st.session_state! Adding a key to a widget automatically creates a corresponding entry in
The final change is with the
st.experimental_set_query_params function. Overwrite the
is_checked variable with whatever was last in your checkbox. Query parameters and your Streamlit checkbox are now synchronized! 🎉
Now you can share your Streamlit apps in the right context and help users play with them!
Massive thanks to Zachary Blackwood for teaching me much of what I know about
st.session_state and for helping with the code. Also thanks to the folks in this Twitter thread who gave me the idea to write about how to use the suggested methods.
Happy Streamlit-ing! 🎈
This is a companion discussion topic for the original entry at https://blog.streamlit.io/how-streamlit-uses-streamlit-sharing-contextual-apps/