State Management

Advanced state management with marimo.state() for reactive programming patterns

State Management

marimo provides mo.state() for managing mutable reactive state in your notebooks. While marimo’s built-in reactivity handles most use cases, state() enables advanced patterns like synchronized UI elements and side effects.

Reactive state is an advanced feature that can introduce cycles and hard-to-debug execution paths. In almost all cases, you should prefer using marimo’s built-in reactive execution and interactivity.

Understanding marimo.state()

The mo.state() function creates mutable reactive state that triggers automatic re-execution of dependent cells when updated.

Basic Usage

import marimo as mo

# Create state with initial value
get_count, set_count = mo.state(0)

This returns:

• Getter function: Reads the current state value
• Setter function: Updates the state value and triggers reactivity

Reading State

# In another cell
current_value = get_count()
mo.md(f"Count: {current_value}")

Updating State

Direct value

# Set to a specific value
set_count(42)

Reactivity Behavior

When you call a state setter:

1. The state value is updated
2. All other cells that reference the getter are automatically re-run
3. By default, the cell that called the setter is not re-run (preventing infinite loops)

Self-Loops

To allow a cell to re-run itself when calling the setter:

get_state, set_state = mo.state(0, allow_self_loops=True)

# This cell will re-run until x reaches 3
x = get_state()
if x < 3:
    set_state(x + 1)

Use allow_self_loops=True carefully - ensure your logic has a termination condition to prevent infinite loops.

Common Use Cases

Synchronizing Multiple UI Elements

Bind multiple UI elements to shared state so they stay synchronized:

# Cell 1: Create shared state
get_value, set_value = mo.state(50)

# Cell 2: Create slider bound to state
slider = mo.ui.slider(
    0, 100,
    value=get_value(),
    on_change=set_value
)
slider

# Cell 3: Create number input bound to same state
number = mo.ui.number(
    0, 100,
    value=get_value(),
    on_change=set_value
)
number

When either element is updated, both will reflect the new value automatically.

Tracking User Interactions

# Track click count
get_clicks, set_clicks = mo.state(0)

button = mo.ui.button(
    label="Click me",
    on_click=lambda _: set_clicks(lambda n: n + 1)
)

mo.md(f"Clicked {get_clicks()} times")

Building State Machines

get_status, set_status = mo.state("idle")

# Different actions based on current state
if get_status() == "idle":
    start_btn = mo.ui.button(
        "Start",
        on_click=lambda _: set_status("running")
    )
elif get_status() == "running":
    stop_btn = mo.ui.button(
        "Stop",
        on_click=lambda _: set_status("idle")
    )

Implementation Details

State Registry

marimo maintains a state registry that tracks all state instances in your notebook. From marimo/_runtime/state.py:

class StateRegistry:
    def __init__(self) -> None:
        # variable name -> state
        self._states: dict[str, StateItem[Any]] = {}
        # id -> variable name for state
        self._inv_states: dict[Id, set[str]] = {}

The registry:

• Uses weak references to avoid memory leaks
• Prunes inactive states when cells are deleted
• Maintains bidirectional mappings for efficient lookups

SetFunctor

The setter is implemented as a typed functor that handles both direct values and functional updates:

class SetFunctor(Generic[T]):
    def __call__(self, update: T | Callable[[T], T]) -> None:
        self._state._value = (
            update(self._state._value)
            if isinstance(update, (types.MethodType, types.FunctionType))
            else update
        )
        ctx.register_state_update(self._state)

Best Practices

Do: Use for UI synchronization

State is ideal for keeping multiple UI elements in sync or managing UI-driven side effects.

Don't: Store UI elements in state

Never store marimo.ui elements in state - this can cause hard-to-diagnose bugs and breaks reactivity.

# ❌ Don't do this
get_widget, set_widget = mo.state(mo.ui.slider(0, 10))

# ✓ Do this instead
get_value, set_value = mo.state(5)
widget = mo.ui.slider(0, 10, value=get_value())

Do: Prefer built-in reactivity

For most cases, marimo’s automatic reactivity is sufficient:

# Usually this is all you need
slider = mo.ui.slider(0, 100)

# In another cell, this automatically updates when slider changes
result = slider.value * 2

Don't: Mutate state directly

Always use the setter function - never mutate the state value directly.

# ❌ Don't do this
get_list, set_list = mo.state([1, 2, 3])
get_list().append(4)  # Bad!

# ✓ Do this instead
set_list(lambda lst: lst + [4])

Testing State

From the test suite (tests/_runtime/test_state.py):

import marimo as mo

# Test basic state update
state, set_state = mo.state(0)
assert state() == 0

set_state(1)
assert state() == 1

# Test functional update
set_state(lambda v: v + 1)
assert state() == 2

# Test with callable objects (not functions)
class Counter:
    called = False
    def __call__(self):
        self.called = True

counter = Counter()
set_state(counter)  # Sets state to counter instance
assert state() == counter
assert not counter.called  # Not called as a function

When to Use State

Use mo.state() when:

• Synchronizing multiple UI elements to the same value
• Implementing complex UI interaction patterns
• Building state machines or multi-step workflows
• Triggering side effects from UI interactions

Don’t use mo.state() when:

• Simple variable assignment works (use marimo’s built-in reactivity)
• You’re just reading UI element values (use .value directly)
• You need to store computation results (use regular variables)

Related APIs

• Reactivity - Understanding marimo’s reactive execution
• Interactivity - Working with UI elements
• UI Elements - Available interactive components