> For the complete documentation index, see [llms.txt](https://docs.digia.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digia.tech/data-and-state/state-management/local-state.md).

# State Containers

A **State Container** is a special widget that creates a localized, isolated pocket of state within the widget tree.

## Lifecycle & Scope

A **State Container** is a specialized widget wrapper that creates a new, isolated scope.

### Lifecycle

* **Lives**: Created when the wrapper widget is mounted on the screen.
* **Dies**: Destroyed immediately when the wrapper is removed from the screen (unmounted).

### Scoping Rules (Strict)

State Containers follow strict hierarchical rules:

1. **Downwards Only**: Variables in a State Container are accessible **only** to the widgets *inside* (children of) that container.
2. **No Parallel Access**: A widget sitting *next to* (parallel) or *above* the State Container cannot access its variables.
3. **Self-Contained Update**: Actions inside the container can update its state, but external actions cannot reach in.

{% @mermaid/diagram content="graph TD
Page\[Page Root]
Sibling\[Sibling Widget<br>❌ Cannot read Local State]
Container\[<b>State Container</b><br>✅ Defines 'timerValue']
Child\[Child Widget<br>✅ Reads 'timerValue']

```
Page --> Sibling
Page --> Container
Container --> Child

style Container fill:#ffccbc,stroke:#333,stroke-width:2px" %}
```

## When to use Local State?

**Performance.**

Imagine you have a **Stopwatch** on your page that updates every millisecond.

* **Without Local State**: If you store the time in Page State, the *entire* text input, image carousel, and scroll view on that page would re-render every millisecond. This causes lag.
* **With Local State**: You wrap just the text showing the time in a State Container. Now, only that tiny text widget rebuilds. The rest of the page remains static and performant.

## How to Create

1. **Wrap**: Right-click a widget and select "Wrap in State Container".
2. **Define**: Add variables in the properties panel for that container.

## How to Update

To modify local state variables, use the **Set State** action from any child widget (e.g., a "Start" button inside the container).

* [See Set State Action](/logic-and-interaction/actions/set-state.md)