# 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](https://docs.digia.tech/data-and-state/data-types). 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](https://docs.digia.tech/data-and-state/data-binding) 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**](https://docs.digia.tech/logic-and-interaction/actions/set-state): For Page/Component or Local variables.
   * [**Set App State Action**](https://docs.digia.tech/logic-and-interaction/actions/set-app-state): 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](https://docs.digia.tech/logic-and-interaction/actions/set-app-state).

#### 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](https://docs.digia.tech/logic-and-interaction/actions/set-state).

#### 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](https://docs.digia.tech/logic-and-interaction/actions/set-state) (Context-aware).