From 62f06e844f30f04db2ac289ef39d2e96646269a2 Mon Sep 17 00:00:00 2001 From: Laura Wilby Date: Thu, 15 Oct 2026 18:32:49 +0200 Subject: [PATCH 1/3] docs: clarify default rerun behavior Co-authored-by: Cursor --- .../concepts/architecture/session-state.md | 4 ++-- .../get-started/fundamentals/main-concepts.md | 18 +++++++++++------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/content/develop/concepts/architecture/session-state.md b/content/develop/concepts/architecture/session-state.md index b7f6dee96..dc707407c 100644 --- a/content/develop/concepts/architecture/session-state.md +++ b/content/develop/concepts/architecture/session-state.md @@ -9,9 +9,9 @@ keywords: session state, statefulness, st.session_state, callbacks, state manage ## What is State? -We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. Streamlit reruns your script from top to bottom every time you interact with your app. Each reruns takes place in a blank slate: no variables are shared between runs. +We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. By default, Streamlit reruns your script from top to bottom every time you interact with your app. You can use [forms](/develop/concepts/architecture/forms) to batch interactions until submission or [fragments](/develop/concepts/architecture/fragments) to rerun only part of your script. Each full-script rerun starts with a blank slate: no regular Python variables are shared between runs. -Session State is a way to share variables between reruns, for each user session. In addition to the ability to store and persist state, Streamlit also exposes the ability to manipulate state using Callbacks. Session state also persists across pages inside a [multipage app](/develop/concepts/multipage-apps). +Session State is a way to share variables between reruns, including fragment reruns, for each user session. In addition to the ability to store and persist state, Streamlit also exposes the ability to manipulate state using Callbacks. Session state also persists across pages inside a [multipage app](/develop/concepts/multipage-apps). In this guide, we will illustrate the usage of **Session State** and **Callbacks** as we build a stateful Counter app. diff --git a/content/get-started/fundamentals/main-concepts.md b/content/get-started/fundamentals/main-concepts.md index c591be95c..9fdd96256 100644 --- a/content/get-started/fundamentals/main-concepts.md +++ b/content/get-started/fundamentals/main-concepts.md @@ -80,17 +80,21 @@ If you are using Streamlit version 1.10.0 or higher, your main script should liv ## Data flow Streamlit's architecture allows you to write apps the same way you write plain -Python scripts. To unlock this, Streamlit apps have a unique data flow: any -time something must be updated on the screen, Streamlit reruns your entire -Python script from top to bottom. +Python scripts. To unlock this, Streamlit apps have a unique data flow: by +default, when something must be updated on the screen, Streamlit reruns your +entire Python script from top to bottom. -This can happen in two situations: +By default, a full-script rerun happens in two situations: - Whenever you modify your app's source code. - Whenever a user interacts with widgets in the app. For example, when dragging a slider, entering text in an input box, or clicking a button. +You can use [forms](/develop/concepts/architecture/forms) to batch widget input +until submission or [fragments](/develop/concepts/architecture/fragments) to +rerun only part of your app. + Whenever a callback is passed to a widget via the `on_change` (or `on_click`) parameter, the callback will always run before the rest of your script. For details on the Callbacks API, please refer to our [Session State API Reference Guide](/develop/api-reference/caching-and-state/st.session_state#use-callbacks-to-update-session-state). And to make all of this fast and seamless, Streamlit does some heavy lifting @@ -277,9 +281,9 @@ st.write(x, 'squared is', x * x) ``` On first run, the app above should output the text "0 squared is 0". Then -every time a user interacts with a widget, Streamlit simply reruns your script -from top to bottom, assigning the current state of the widget to your variable -in the process. +with the default widget behavior, every time a user interacts with a widget, +Streamlit simply reruns your script from top to bottom, assigning the current +state of the widget to your variable in the process. For example, if the user moves the slider to position `10`, Streamlit will rerun the code above and set `x` to `10` accordingly. So now you should see the From 333e3f4ab35120744a505733b84a7ab890320541 Mon Sep 17 00:00:00 2001 From: Laura Wilby Date: Thu, 15 Oct 2026 18:52:07 +0200 Subject: [PATCH 2/3] docs: mention ignored widget reruns Co-authored-by: Cursor --- content/develop/concepts/architecture/session-state.md | 2 +- content/get-started/fundamentals/main-concepts.md | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/content/develop/concepts/architecture/session-state.md b/content/develop/concepts/architecture/session-state.md index dc707407c..e6d437741 100644 --- a/content/develop/concepts/architecture/session-state.md +++ b/content/develop/concepts/architecture/session-state.md @@ -9,7 +9,7 @@ keywords: session state, statefulness, st.session_state, callbacks, state manage ## What is State? -We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. By default, Streamlit reruns your script from top to bottom every time you interact with your app. You can use [forms](/develop/concepts/architecture/forms) to batch interactions until submission or [fragments](/develop/concepts/architecture/fragments) to rerun only part of your script. Each full-script rerun starts with a blank slate: no regular Python variables are shared between runs. +We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. By default, Streamlit reruns your script from top to bottom every time you interact with your app. Some widgets accept `on_change="ignore"` to update without triggering a rerun; Python receives the new value on the next rerun. You can also use [forms](/develop/concepts/architecture/forms) to batch interactions until submission or [fragments](/develop/concepts/architecture/fragments) to rerun only part of your script. Each full-script rerun starts with a blank slate: no regular Python variables are shared between runs. Session State is a way to share variables between reruns, including fragment reruns, for each user session. In addition to the ability to store and persist state, Streamlit also exposes the ability to manipulate state using Callbacks. Session state also persists across pages inside a [multipage app](/develop/concepts/multipage-apps). diff --git a/content/get-started/fundamentals/main-concepts.md b/content/get-started/fundamentals/main-concepts.md index 9fdd96256..1bf53e25c 100644 --- a/content/get-started/fundamentals/main-concepts.md +++ b/content/get-started/fundamentals/main-concepts.md @@ -91,9 +91,11 @@ By default, a full-script rerun happens in two situations: - Whenever a user interacts with widgets in the app. For example, when dragging a slider, entering text in an input box, or clicking a button. -You can use [forms](/develop/concepts/architecture/forms) to batch widget input -until submission or [fragments](/develop/concepts/architecture/fragments) to -rerun only part of your app. +Some widgets accept `on_change="ignore"` to update without triggering a rerun; +Python receives the new value on the next rerun. You can also use +[forms](/develop/concepts/architecture/forms) to batch widget input until +submission or [fragments](/develop/concepts/architecture/fragments) to rerun +only part of your app. Whenever a callback is passed to a widget via the `on_change` (or `on_click`) parameter, the callback will always run before the rest of your script. For details on the Callbacks API, please refer to our [Session State API Reference Guide](/develop/api-reference/caching-and-state/st.session_state#use-callbacks-to-update-session-state). From 4f6eb4dbd56ebc3c1006b16eaff09f0da22b7955 Mon Sep 17 00:00:00 2001 From: Laura Wilby Date: Thu, 15 Oct 2026 19:03:38 +0200 Subject: [PATCH 3/3] docs: distinguish variables from Session State Co-authored-by: Cursor --- content/develop/concepts/architecture/session-state.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/develop/concepts/architecture/session-state.md b/content/develop/concepts/architecture/session-state.md index e6d437741..9038e183a 100644 --- a/content/develop/concepts/architecture/session-state.md +++ b/content/develop/concepts/architecture/session-state.md @@ -9,9 +9,9 @@ keywords: session state, statefulness, st.session_state, callbacks, state manage ## What is State? -We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. By default, Streamlit reruns your script from top to bottom every time you interact with your app. Some widgets accept `on_change="ignore"` to update without triggering a rerun; Python receives the new value on the next rerun. You can also use [forms](/develop/concepts/architecture/forms) to batch interactions until submission or [fragments](/develop/concepts/architecture/fragments) to rerun only part of your script. Each full-script rerun starts with a blank slate: no regular Python variables are shared between runs. +We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. By default, Streamlit reruns your script from top to bottom every time you interact with your app. Some widgets accept `on_change="ignore"` to update without triggering a rerun; Python receives the new value on the next rerun. You can also use [forms](/develop/concepts/architecture/forms) to batch interactions until submission or [fragments](/develop/concepts/architecture/fragments) to rerun only part of your script. Each full-script rerun starts with a blank slate for regular Python variables, but values stored in Session State persist across full-script and fragment reruns. -Session State is a way to share variables between reruns, including fragment reruns, for each user session. In addition to the ability to store and persist state, Streamlit also exposes the ability to manipulate state using Callbacks. Session state also persists across pages inside a [multipage app](/develop/concepts/multipage-apps). +Session State is scoped to each user session. Streamlit also exposes the ability to manipulate state using Callbacks. Session State persists across pages inside a [multipage app](/develop/concepts/multipage-apps). In this guide, we will illustrate the usage of **Session State** and **Callbacks** as we build a stateful Counter app.