Maintaining Interactive State in Streamlit Apps with session_state

Desired outcome

Build a Streamlit widget‑driven app where user interactions (e.g., button clicks, text input) persist across script reruns without relying on external storage or URL parameters.

Prerequisites

• Python 3.8+ installed.
• Streamlit library (≥1.22) installed via pip install streamlit.
• Basic familiarity with running a Streamlit script (streamlit run app.py).

Focused procedure

1. Initialize session_state keys. At the very top of your script, before any widget definitions, check for each key you intend to use and assign a default if it does not exist. This prevents the key from being recreated on every rerun.

   import streamlit as st
   
   if 'counter' not in st.session_state:
       st.session_state['counter'] = 0
   if 'user_name' not in st.session_state:
       st.session_state['user_name'] = ''

2. Bind widgets to session_state. Pass the key argument to widgets so Streamlit automatically synchronizes the widget value with the corresponding session_state entry.

   st.text_input('Your name', key='user_name')
   st.button('Increment', on_click=lambda: st.session_state.update({'counter': st.session_state['counter'] + 1}))
   st.write(f'Counter: {st.session_state["counter"]}')
   st.write(f'Hello, {st.session_state["user_name"] or "stranger"}!')

3. Read and use state elsewhere. Anywhere in the script you can read st.session_state['key'] to drive conditional rendering, data loading, or navigation.

   if st.session_state['counter'] > 5:
       st.success('You have clicked the button more than five times!')

4. Provide a reset mechanism. Add a button that clears specific keys or the entire state when you want to return to a clean slate.

   if st.button('Reset all'):
       st.session_state.clear()
       # Re‑initialize defaults if needed
       if 'counter' not in st.session_state:
           st.session_state['counter'] = 0
       if 'user_name' not in st.session_state:
           st.session_state['user_name'] = ''

Expected checks

• After entering a name and clicking the Increment button several times, the counter value and name should remain visible when you interact with other widgets or resize the browser window.
• Opening a second browser tab pointing to the same http://localhost:8501 URL should show an independent counter and name field, confirming per‑session isolation.
• Pressing the Reset all button should return the counter to 0 and clear the name field; subsequent interactions start from this clean state.

Recovery options

If the app behaves unexpectedly (e.g., state appears stale), you can:

• Manually delete the browser’s local storage for the Streamlit site (usually under Application → Storage in DevTools) to force a fresh session.
• Restart the Streamlit server (Ctrl+C in the terminal, then streamlit run app.py) to clear any in‑memory server‑side caches.