@@ -0,0 +1 @@
+Document changing a state var's default through its field, including per-component defaults and browser storage keys in `ComponentState`.
@@ -44,15 +44,32 @@ def page():
 State.get_fields()["_items"].default_value()
 ```
 
-## Assigning a default through a state class
+## Assigning a state var through its class
 
-On 0.9, `State.count = 10` replaced the class attribute, but new instances still started at the declared default. In 0.10 it updates the var's default and the var stays a var ([#7461](https://github.com/reflex-dev/reflex/pull/7461)); [Changing Defaults](/docs/vars/base-vars/#changing-defaults) has the full rules. Check these before relying on it:
+On 0.9, `State.count = 10` replaced the class attribute, but new instances still started at the declared default. In 0.10 a state var is a descriptor on its class, and assigning over it raises `TypeError` instead of breaking the var. This includes pytest's `monkeypatch.setattr` and `unittest.mock.patch.object` on a var. Change the default on the var's field, patch the field in tests, and declare class-level configuration as `ClassVar`:
 
-- It changes the default for values not yet stored on an instance, which includes every new session and `reset()`. A value already stored on an instance keeps it.
-- The value must satisfy the var's annotation, or `TypeError: Invalid default for field` is raised. An unannotated var is typed from its default, so `_client = None` accepts only `None`; annotate the var with the type you assign.
-- A zero-argument callable that the annotation does not accept, such as a function or a class, is called once during the assignment to check what it returns, then becomes the default factory. Do not assign something whose call has side effects.
-- Mutable defaults are copied for every instance. A live client, lock or connection assigned to an `Any` or `Optional[...]` var is accepted, but reading the var on a new instance then raises `TypeError: cannot pickle '_thread.lock' object`. Declare an object that all sessions share as `ClassVar[...]`, which is never copied.
-- Assigning on a mixin only affects states created afterwards. Do not assign defaults in event handlers, lifespan tasks, or at any other time after the app has started running: such an assignment only affects the worker process that ran it.
+```python
+from typing import ClassVar
+from unittest import mock
+
+import httpx
+
+import reflex as rx
+
+
+class State(rx.State):
+    count: int = 0
+    _client: ClassVar[httpx.AsyncClient | None] = None
+
+
+State.__fields__["count"].default = 10
+State._client = httpx.AsyncClient()  # a ClassVar stays an ordinary class attribute
+
+with mock.patch.object(State.__fields__["count"], "default", 99):
+    ...
+```
+
+[Changing Defaults](/docs/vars/base-vars/#changing-defaults) has the details, including mutable defaults and browser storage vars.
 
 ## Calling inherited handlers from background tasks
 
 
@@ -108,7 +108,7 @@ class EditableText(rx.ComponentState):
         # Set the initial value of the State var.
         initial_value = props.pop("initial_value", None)
         if initial_value is not None:
-            cls.text = initial_value
+            cls.__fields__["text"].default = initial_value
 
         # Form elements for editing, saving and reverting the text.
         edit_controls = rx.hstack(
@@ -160,10 +160,29 @@ def editable_text_example():
     )
 ```
 
-Assigning `cls.text` in `get_component` sets the default for that component's new
-state class. Other components keep their own defaults, and `cls.text` still
-references the frontend var when building the UI. Resetting the component's state
-restores its last configured default.
+Setting `cls.__fields__["text"].default` in `get_component` sets the default for
+that component's new state class, which owns a copy of each field: other
+components keep their own defaults. Resetting the component's state restores the
+configured default. Assigning `cls.text` itself raises `TypeError`, because
+`cls.text` is the var the UI references; see
+[Changing Defaults](/docs/vars/base-vars/#changing-defaults).
+
+A browser storage var declared with a `name`, such as
+`rx.LocalStorage("light", name="theme")`, stores every component's value under
+that one key, so the components overwrite each other's stored value. To persist a
+value per component, give each component its own storage value in
+`get_component`, here named by a `key` prop that identifies the component, or
+leave `name` unset so each component state gets its own key:
+
+```python
+class ThemeToggle(rx.ComponentState):
+    theme: str = rx.LocalStorage("light", name="theme")
+
+    @classmethod
+    def get_component(cls, key: str, initial: str = "light", **props):
+        cls.__fields__["theme"].default = rx.LocalStorage(initial, name=f"theme_{key}")
+        return rx.text(cls.theme, **props)
+```
 
 ```python eval
 rx.divider()
 
@@ -75,59 +75,65 @@ def ticker_example():
 
 ## Changing Defaults
 
-Assigning a value to a declared var on its state class updates the default for
-values that have not yet been initialized and for `reset()`. This works for both
-frontend and backend vars. Values already stored on a state instance stay the
-same, and mutable defaults are copied for each instance. Reset uses the last
-configured default. Defaults are not part of the saved-state schema, so changing
-one does not invalidate state saved by this release or later.
-
-Assigned defaults must match the field's declared type. Var and Field assignments
-are rejected, including fresh `rx.field(...)` objects, unless they restore a
-default as described below. Declare a `ClassVar[rx.Var]` to
-store a Var reference, or define a computed var to read another field at runtime.
-A callable the annotation accepts, such as for a `Callable` or `Any` var, is
-stored as the default. Otherwise, assigning a zero-argument callable updates the
-default factory: Reflex calls it once when assigned to validate its result, then
-calls it whenever an instance needs a new default or resets. If that validation
-call fails or returns an invalid default, the previous default remains in place.
-A factory that produces a browser storage value is called once at assignment,
-and its result becomes the default so the storage name and options are kept.
-Assigning a plain string to a var whose default is a browser storage value, such
-as `rx.LocalStorage("light", name="theme")`, or whose `default_factory` produces
-one, keeps that storage type, name and options and changes only the value.
-Frontend vars remain usable in the UI after assigning a new default value or
-factory.
-
-An inherited var belongs to the state that declared it, so assigning a default
-through a subclass also changes that declaring state's default. Each generated
-`ComponentState` class owns its copied fields, allowing
+A state var is a descriptor on its state class, so assigning to it through the
+class raises `TypeError` instead of replacing the var. To change a var's default,
+set it on the var's field:
+
+```python
+class WatchlistState(rx.State):
+    ticker: str = "AAPL"
+    symbols: list[str] = []
+
+
+WatchlistState.__fields__["ticker"].default = "MSFT"
+WatchlistState.__fields__["symbols"].default_factory = lambda: ["AAPL", "MSFT"]
+```
+
+The default applies to values not yet stored on an instance, which includes
+every new session and `reset()`. Values already stored on an instance stay the
+same. A field uses its `default` when one is set, and otherwise calls its
+`default_factory`. A `default` is shared by every instance, so give a mutable
+default a `default_factory` that builds a new value each time. The field does
+not check the value against the var's annotation. A browser storage var keeps
+its storage name and options only with a storage value as its default, such as
+`rx.LocalStorage("dark", name="theme")`, or, for a var annotated with a storage
+type, a `default_factory` that returns one. Given a plain string, a var
+annotated `str` becomes an ordinary var, and one annotated with a storage type,
+such as `rx.LocalStorage`, stays in browser storage under the default key and
+options.
+
+An inherited var belongs to the state that declared it, so changing its field
+also changes the default for every state that inherits it. Each generated
+`ComponentState` class owns copies of its fields, allowing
 [`get_component` to configure defaults](/docs/state-structure/component-state/#passing-props)
 independently for each component.
 
-Assigning a var's own field or Var back to its state class, as read through the
-class before a change, or deleting the class attribute undoes the most recent
-default assignment. Testing tools such as pytest's `monkeypatch.setattr` and
-`unittest.mock.patch.object` restore a patched default this way, including a
-patch made through a subclass.
+In tests, patch the field rather than the class attribute, which raises the same
+`TypeError`:
 
-```md alert warning
-# Annotate the var, and keep shared objects out of defaults.
-
-An unannotated var is typed from its default, so `_client = None` only accepts
-`None` later: annotate the var with the type you will assign. Defaults are copied
-for every instance, so a live client, lock, or connection cannot be shared this
-way. Assigning one to an `Any` or `Optional[...]` var is accepted, but reading the
-var on a new instance then raises `TypeError: cannot pickle '_thread.lock' object`.
-Declare an object that all sessions share as a `ClassVar`.
+```python
+from unittest import mock
+
+with mock.patch.object(WatchlistState.__fields__["ticker"], "default", "MSFT"):
+    ...
 ```
 
+Declare class-level configuration, such as a client or a lock, as a `ClassVar`.
+It stays an ordinary class attribute, so assigning it through the class is
+allowed, and it is never copied for each instance. Each backend worker process
+holds its own value, though, so a lock only serializes the sessions on its own
+worker. A value set at import time, such as at module level, starts the same in
+every worker, but a change made after the workers start, such as in an event
+handler, never reaches the other workers. Keep a value that sessions must share
+at runtime in an [`rx.SharedState`](/docs/state-structure/shared-state/) or an
+external store.
+
 ```md alert warning
-# Assign defaults before the app starts running.
+# Change defaults before the app starts running.
 
-Assigning on a mixin only affects states created afterwards. Do not assign
-defaults in event handlers, lifespan tasks, or at any other time after the app
-has started running: such an assignment only affects the worker process that ran
+Changing a default on a mixin only affects states created afterwards. Do not
+change defaults in event handlers, lifespan tasks, or at any other time after the
+app has started running: such a change only affects the worker process that made
 it.
 ```
 
@@ -164,9 +170,10 @@ Reading `MyState._token` through the class returns its field descriptor, whose
 `default_value()` method returns the default (a fresh copy if it is mutable). Use
 it to build the UI from a constant, such as
 `rx.foreach(MyState._options.default_value(), rx.text)` for a backend var
-`_options`. Assigning to `MyState._token` updates its default as described above.
+`_options`. Assigning to `MyState._token` raises `TypeError`: change its default
+through its field as described above.
 
-For configuration shared by all sessions, declare a `ClassVar` instead:
+For class-level configuration, declare a `ClassVar` instead:
 
 ```python
 from typing import ClassVar
@@ -183,6 +190,8 @@ MyState._endpoint = "https://example.com/v2"
 `ClassVar` values are ordinary class attributes and are not part of session state.
 Reading one on the class returns the plain value, and an object that cannot be
 copied, such as a client or lock, is shared rather than copied for each instance.
+Each backend worker holds its own value, as described under
+[Changing Defaults](#changing-defaults).
 
 ```python demo exec
 import numpy as np
 
@@ -1 +1 @@
-Configure per-component defaults in `ComponentState.get_component` with assignments such as `cls.count = 10`. Reset restores the last configured default. Defaults are no longer part of the saved-state schema, so changing one keeps state saved by this release or later loadable. Browser storage vars keep their storage settings when a factory is assigned, and declared factories are honored when compiled and reset.
+Defaults are no longer part of the saved-state schema, so changing one keeps state saved by this release or later loadable. A browser storage var annotated with a storage type, such as `rx.Field[rx.LocalStorage]`, and declared with a `default_factory` compiles with the storage options the factory produces, and `reset()` restores the factory's value.
@@ -0,0 +1 @@
+Assigning a state var through its state class, such as `State.count = 10`, raises `TypeError` instead of replacing the var; so do pytest's `monkeypatch.setattr` and `unittest.mock.patch.object` on a var. Change a default with `State.__fields__["count"].default = 10`, patch the field in tests, and declare class-level configuration as `ClassVar`.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Document changing a state var's default through its field, including per-component defaults and browser storage keys in `ComponentState`.
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		-Configure per-component defaults in `ComponentState.get_component` with assignments such as `cls.count = 10`. Reset restores the last configured default. Defaults are no longer part of the saved-state schema, so changing one keeps state saved by this release or later loadable. Browser storage vars keep their storage settings when a factory is assigned, and declared factories are honored when compiled and reset.
	`1`	+Defaults are no longer part of the saved-state schema, so changing one keeps state saved by this release or later loadable. A browser storage var annotated with a storage type, such as `rx.Field[rx.LocalStorage]`, and declared with a `default_factory` compiles with the storage options the factory produces, and `reset()` restores the factory's value.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Assigning a state var through its state class, such as `State.count = 10`, raises `TypeError` instead of replacing the var; so do pytest's `monkeypatch.setattr` and `unittest.mock.patch.object` on a var. Change a default with `State.__fields__["count"].default = 10`, patch the field in tests, and declare class-level configuration as `ClassVar`.