state

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.