# App State

**App State** variables are global variables that live at the highest level of your application. They are accessible from **any page** and **any component** in your project.

{% @mermaid/diagram content="graph TD
subgraph GlobalScope \[Global Application Scope]
AppState\["<b>App State</b><br><i>(Global Memory)</i>"]

```
    %% Nodes
    PageA[Page A]
    PageB[Page B]
    Comp[Component]
    
    %% Connections
    AppState -->|Read/Write| PageA
    AppState -->|Read/Write| PageB
    AppState -->|Read/Write| Comp
end

style AppState fill:#ffecb3,stroke:#333,stroke-width:2px
style GlobalScope fill:#f9f9f9,stroke:#e0e0e0,stroke-width:1px" %}
```

{% embed url="<https://www.youtube.com/watch?v=lZ2hGiaVBVY>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=lZ2hGiaVBVY>

## Lifecycle & Persistence

App State variables live as long as the application is running. However, you can choose to make them survive even after the app is closed using **Persistence**.

* **Non-Persisted**: Value is lost when the app is closed (cleared from memory).
* **Persisted**: Value is saved to the device's disk (Key-Value storage). It is automatically reloaded when the app restarts.

> \[!IMPORTANT] **Key-Value Storage**: Persisted state is backed by simple key-value storage (like Shared Preferences).
>
> * **Do NOT** treat it like a database. You cannot query it.
> * **Do NOT** store massive datasets.

## When to use App State?

Choose App State when data needs to:

1. **Survive Navigation**: Data shouldn't be lost when moving from Page A to Page B.
2. **Be Shared**: Multiple screens need access to the same data (e.g., a Shopping Cart).
3. **Persist**: You want to remember the data even after the user closes the app (e.g., `authToken`, `isDarkMode`).

## How to Create App State Variables

1. Open the **App Settings** panel (usually the gear icon).
2. Select the **App State** tab.
3. Click **+ Add State Variable**.
4. Define the **Name**, **Type**, and **Default Value**.

## How to Use App State

There are two primary ways to consume App State in your UI:

### 1. Expressions (Passive)

Use this when you just need to **read** the value at a specific moment, or if the widget handles updates internally.

* **Usage**: Bind a Text widget's value to `appState.userName`.

### 2. StreamBuilder (Reactive)

App State exposes a **Stream** of changes. If you want your UI to automatically rebuild whenever the variable changes, you must "listen" to it.

* **Usage**: Wrap your widget in a **StreamBuilder**.
* **Source**: Select the specific App State variable as the stream source.

| Goal                                   | Method            |
| -------------------------------------- | ----------------- |
| Just display a value                   | **Expression**    |
| Update UI instantly when value changes | **StreamBuilder** |

## Updating App State

To change the value of a global variable, use the **Set App State** action.

* [See Set App State Action](https://docs.digia.tech/logic-and-interaction/actions/set-app-state)

## Best Practices

> \[!TIP]
>
> * **Naming**: Use clear prefixes like `is` for Booleans (`isLoggedIn`) or `has` (`hasSeenOnboarding`).
> * **Reset on Logout**: If you store user data in App State, remember to specific an action to **Clear/Reset** these variables when the user logs out.


---

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