Suppose a to-do app needs to remember tasks as you add them. Streamlit reruns its Python code from top to bottom when the page changes, so an ordinary task list created at the top of the script resets. `st.session_state` keeps values available across those reruns. section 4.5.1 section 4.6
A session lasts from opening the app until refreshing or closing the page. Two tabs showing the same app have separate sessions. Session state is therefore useful for an active interaction, not for saving data that must survive a refresh. section 4.4.1 section 4.1.2
Remember a button count
Initialize a value only if its key is absent, then change and display it: ```python if "number" not in st.session_state: st.session_state.number = 0 if st.button("Increment"): st.session_state.number += 1 st.info(f"Number: {st.session_state.number}") ``` Each click reruns the app. The existence check prevents initialization from setting the count back to zero each time. section 4.4.1
Session state works much like a dictionary: assign or retrieve a value with `st.session_state["number"]`, check whether a key exists, iterate over items, or delete a key. Dot notation, such as `st.session_state.number`, also works. section 4.4.1
Keep a to-do list
For a list that should survive reruns, initialize it once with `st.session_state.task_list = []` if the key is absent. Then set `task_list = st.session_state.task_list`. Existing functions can append tasks to that list without being rewritten to use the longer expression; adding another task no longer erases the previous ones. section 4.5.1
A widget given a key also exposes its value through session state. To set a dropdown programmatically, assign its keyed value *before* the widget code runs; setting the key after the widget renders does not work. For shareable dashboard selections, query parameters can supply initial widget values, while selected session-state values can be written back to the URL. Apply URL defaults only when the keys are absent, or later user changes will be overwritten. section 7.6.2 section 7.6.3
Session state can also drive conditional screens in a linear app. When debugging, display the value with `st.info` and step through what each rerun changes. Frontend tests can inspect `AppTest.session_state` before and after simulated inputs and button clicks, checking both stored results and the UI they produce. section 9.8 section 11.4.1 section 4.6
Do not confuse an app session with a database session. `st.session_state` remembers values during an app session; a SQLAlchemy database session is used to execute queries and, when needed, commit changes. Data that must remain after a page refresh needs storage beyond this session-scoped to-do list. section 4.4.1 section 8.2.5 section 4.1.2
