Mutable reactive state.
Reactive state is an advanced feature that you likely don’t need. It makes it possible to introduce cycles and hard-to-debug code execution paths. In almost all cases, you should prefer using marimo’s built-in reactive execution and interactivity.
- a getter function that reads the state value
- a setter function to set the state’s value
When you call the setter function and update the state value in one cell, all other cells that read any global variables assigned to the getter will automatically run. By default, the cell that called the setter function won’t be re-run, even if it references the getter. To allow a state setter to possibly run the caller cell, set the keyword argument allow_self_loops=True.
Usage
Create state
get_count, set_count = mo.state(0)
Read the value
Update the state
Update based on current value
set_count(lambda value: value + 1)
Synchronizing multiple UI elements
get_state, set_state = mo.state(0)
# Updating the state through the slider will recreate the number (below)
slider = mo.ui.slider(0, 100, value=get_state(), on_change=set_state)
# Updating the state through the number will recreate the slider (above)
number = mo.ui.number(0, 100, value=get_state(), on_change=set_state)
# slider and number are synchronized to have the same value (try it!)
[slider, number]
Signature
mo.state(
value: T,
allow_self_loops: bool = False
) -> tuple[State[T], Callable[[T], None]]
Parameters
Initial value of the state.
If True, a cell that calls a state setter and also references its getter will be re-run. Defaults to False.
Returns
tuple[State[T], Callable[[T], None]]
A tuple of (getter function, setter function). The getter function retrieves the state value; the setter function takes a new value or a function that updates the current value.
Important Notes
Do not store marimo.ui elements in state; doing so can cause hard-to-diagnose bugs.
UIElement on_change handlers to trigger side-effects when an element’s value is updated; however, you should prefer using marimo’s built-in reactive execution for interactive elements.