# State Management

**State** is the "memory" of your application. It constitutes any data that can change over time—like what the user has typed into a form, whether a toggle is checked, or the current item loaded from an API.

### Why do we need State Management?

Without State Management, your app would be static. It wouldn't "remember" anything. When you change a value, the UI needs to know about it so it can redraw itself to reflect that change.

State Management provides a structured way to:

1. **Store** dynamic data.
2. **Update** that data in response to user actions (clicks, typing).
3. **Reflect** those updates on the UI automatically.

{% @mermaid/diagram content="graph LR
A\[User Interaction] -->|Triggers Action| B(Update Variable)
B -->|State Change| C{State Manager}
C -->|Notifies| D\[UI Widget]
D -->|Rebuilds| E\[New Interface]
style C fill:#f9f,stroke:#333,stroke-width:2px" %}

## State Variables

**State Variables** are essentially just [Variables](/data-and-state/data-types.md). They provide a way to reference your application's memory by a specific name (e.g., `isVisible`, `counterValue`).

### Key Characteristics

1. **Initial Value**: Every state variable acts as a container created with an initial value (default).
2. **Usage**: Once created, you can use the variable in an [Expression](/data-and-state/data-binding.md) bound to a widget property. When the variable changes, the widget updates automatically.
3. **Updating**: You can modify the value of these variables using specific Actions:
   * [**Set State Action**](/logic-and-interaction/actions/set-state.md): For Page/Component or Local variables.
   * [**Set App State Action**](/logic-and-interaction/actions/set-app-state.md): For Global variables.

### Creating State Variables

In Digia, you can create state variables at three distinct levels, which determines their scope and lifecycle.

1. **Global Level (App State)**: Created in the App Settings. Accessible everywhere.
2. **Page or Component Level**: Created in the Page/Component configuration. Accessible only within that screen or component.
3. **Local Level (State Container)**: Inserted as a parent widget in the tree (the **State Container** widget) to manage state for just that specific child sub-tree.

### State Scope

**Scope** determines where a variable can be **read** (accessed) and where it can be **modified**.

Think of it like scopes in a programming language (e.g., JavaScript):

* **App State** ≈ Global Variable (Accessible everywhere).
* **Page State** ≈ File Scope (Accessible only inside the file).
* **Local State** ≈ Function/Block Scope `{ }` (Accessible only inside a specific function/block).

{% @mermaid/diagram content="graph TD
Global\[<b>Global State</b><br><i>var: authToken</i>]

```
subgraph Page [<b>Page: Home Screen</b>]
    direction TB
    PageState[<b>Page State Container</b><br><i>var: selectedTab</i>]
    
    WidgetA[<b>Header Widget</b><br>Reads: <i>authToken, selectedTab</i>]
    
    subgraph FeedItem ["<b>Feed Item</b> (Local Scope)"]
        LocalState[<b>State Container</b><br><i>var: likeCount</i>]
        WidgetB[<b>Like Button</b><br>Reads: <i>authToken, selectedTab, likeCount</i>]
    end
end

%% Flow/Hierarchy
Global --> Page
PageState --> WidgetA
PageState --> FeedItem
LocalState --> WidgetB

%% Styling
style Global fill:#ffecb3,stroke:#333
style Page fill:#e1f5fe,stroke:#333,stroke-dasharray: 5 5
style PageState fill:#b3e5fc,stroke:#333,stroke-width:2px
style FeedItem fill:#fff3e0,stroke:#333,stroke-dasharray: 5 5
style LocalState fill:#ffccbc,stroke:#333,stroke-width:2px
style WidgetA fill:#fff,stroke:#333
style WidgetB fill:#fff,stroke:#333" %}
```

#### 1. App State (Global)

* **Definition**: Variables defined at the application root.
* **Lifecycle**: Lives as long as the app is running. (Persists if configured).
* **Access**: Can be **Read** and **Updated** from *any* page or component.
* **Update Action**: [Set App State](/logic-and-interaction/actions/set-app-state.md).

#### 2. Page & Component State

* **Definition**: Variables defined on a specific Page or Component.
* **Lifecycle**: Created when the page triggers `OnLoad`. Destroyed when the user navigates away (page is popped).
* **Access**: Can be **Read** anywhere on that page. Can be **Updated** by any action on that page.
* **Update Action**: [Set State](/logic-and-interaction/actions/set-state.md).

#### 3. Local State (via State Container)

* **Definition**: Variables managed by a **State Container** widget inserted into the widget tree.
* **Lifecycle**: Alive only as long as that specific widget exists in the tree.
* **Access**: accessible *only* to the children of that State Container.
* **Update Action**: [Set State](/logic-and-interaction/actions/set-state.md) (Context-aware).


---

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