Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

docs(ui): clarify UIElement value is read-only (#9382)

onthebedbf0468d2a707
diff --git a/marimo/_plugins/ui/_core/ui_element.py b/marimo/_plugins/ui/_core/ui_element.py
index 0cecdfb00d..9915dbc711 100644
--- a/marimo/_plugins/ui/_core/ui_element.py
+++ b/marimo/_plugins/ui/_core/ui_element.py
@@ -101,7 +101,9 @@ class UIElement(Html, Generic[S, T]):
**Attributes.**
- - value: The value of the `UIElement`.
+ - value: The current value of the `UIElement`. Read-only; it reflects
+ frontend state and can't be assigned directly. If you need to
+ imperatively drive UI state, use `mo.state()`.
**Methods.**
@@ -310,7 +312,12 @@ class UIElement(Html, Generic[S, T]):
@property
def value(self) -> T:
- """The element's current value."""
+ """The element's current value.
+
+ Read-only; marimo updates it when the UI element changes in the
+ frontend. If you need to imperatively drive UI state, use
+ `mo.state()` instead of assigning to this property.
+ """
if self._ctx is None:
return self._value