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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/data-and-state/state-management/local-state.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.