Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/marimo-team/marimo/llms.txt

Use this file to discover all available pages before exploring further.

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.
This function takes an initial value and returns:
  • 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

get_count()

​
Update the state

set_count(1)

​
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

​
value
T
required
Initial value of the state.
​
allow_self_loops
bool
default:"False"
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.
Never mutate the state directly. You should only change its value through its setter. You can use this function with 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us