> ## 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.

# state

Mutable reactive state.

<Warning>
  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](https://docs.marimo.io/guides/reactivity) and [interactivity](https://docs.marimo.io/guides/interactivity).**
</Warning>

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

```python theme={null}
get_count, set_count = mo.state(0)
```

### Read the value

```python theme={null}
get_count()
```

### Update the state

```python theme={null}
set_count(1)
```

### Update based on current value

```python theme={null}
set_count(lambda value: value + 1)
```

### Synchronizing multiple UI elements

```python theme={null}
get_state, set_state = mo.state(0)
```

```python theme={null}
# Updating the state through the slider will recreate the number (below)
slider = mo.ui.slider(0, 100, value=get_state(), on_change=set_state)
```

```python theme={null}
# Updating the state through the number will recreate the slider (above)
number = mo.ui.number(0, 100, value=get_state(), on_change=set_state)
```

```python theme={null}
# slider and number are synchronized to have the same value (try it!)
[slider, number]
```

## Signature

```python theme={null}
mo.state(
    value: T,
    allow_self_loops: bool = False
) -> tuple[State[T], Callable[[T], None]]
```

## Parameters

<ParamField path="value" type="T" required>
  Initial value of the state.
</ParamField>

<ParamField path="allow_self_loops" type="bool" default="False">
  If `True`, a cell that calls a state setter and also references its getter will be re-run. Defaults to `False`.
</ParamField>

## Returns

<ParamField path="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.
</ParamField>

## Important Notes

<Warning>
  Do not store `marimo.ui` elements in state; doing so can cause hard-to-diagnose bugs.
</Warning>

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.