# State Container

The **State Container** is a simple widget that wraps **one child** and gives it its own **local state**.\
Use it when a part of your UI needs to manage its own state without involving the whole page or global state.

{% embed url="<https://youtu.be/RtM5l8G1rlE?si=iwURVC9A899wdncT>" %}

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

### Core Concepts

1. **Local, Scoped State**
   * The state lives **inside** the State Container and is only available to its **child**.
   * Each State Container instance has **its own copy** of state (no sharing by default).
2. **Accessing Local State**
   * You can access local state variables directly by name: `isExpanded`, `count`, `selectedIndex`
   * Or with the container name prefix: `statecontainerName.isExpanded`
   * This allows flexible referencing based on your naming preferences
3. **State-Driven Rebuilds**
   * You read values via something like `state.count`, `state.isExpanded`, `state.selectedIndex`.
   * Use the **Set State** action to update state values and trigger UI rebuilds.
4. **Actions for State Management**
   * Use the **Set State** action to update local state variables
   * Use the **Rebuild State** action to force UI updates when needed
   * These actions work with the state container to manage local state changes
5. **Encapsulation**
   * UI logic is **packaged** with the widget that uses it.
   * You don't need to push every small boolean or counter to a page-level or global store.
6. **Ideal for Micro-Interactions**
   * Great for small, self-contained interactions:
     * Toggles → Use **Set State** action to update `isOn: not(isOn)`
     * Counters → Use **Set State** action to update `count: add(count,1)`
     * Selection → Use **Set State** action to update `selectedIndex: index`

If many widgets need the **same** state, or that state affects the **whole screen**, that's your sign to **lift the state up** out of the State Container.

### Best Practices

* Use for **small, UI-specific logic**:
  * Toggles, counters, per-card expand/collapse, local selection.
* Keep state **minimal and clear**:
  * Prefer simple keys like `isOpen`, `count`, `activeTab`.
* If multiple widgets must share the same state or it affects the whole screen,\
  move that state to a **higher-level** widget instead of a State Container.

### Properties

The State Container widget provides local state management capabilities. You can define local state variables that are scoped to the container and its child widgets.

#### Defining Local Variables

* **State Variables**: Add and configure local state variables in the State Variables section
* **Variable Types**: Support for various data types including strings, numbers, booleans, objects, and arrays
* **Initial Values**: Set initial values for each state variable
* **Scope**: Variables are only accessible within the State Container and its child widgets

Beyond the state variables, the State Container does not have specific configuration properties beyond the default layout and interaction properties.

### Actions for State Management

To manage state within a State Container, use these actions:

#### Set State Action

* **Purpose**: Update local state variables with new values
* **How to use**:
  1. Add the **Set State** action to a widget event (onClick, onChanged, etc.)
  2. Select the State Container from the State dropdown
  3. Add state variable updates in the State Updates section
  4. Optionally enable "Rebuild UI" for immediate visual updates

*Reference:* [*Set State Action*](https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/building-ui/actions/set-state.md)

#### Rebuild State Action

* **Purpose**: Force a UI rebuild of the State Container without changing state values
* **How to use**:
  1. Add the **Rebuild State** action to a widget event
  2. Select the State Container from the State dropdown
  3. This triggers a re-render of dependent widgets

*Reference:* [*Rebuild State Action*](https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/building-ui/actions/rebuild-state.md)

### Default Properties

The State Container widget supports no default property.

### Use Cases

Use **State Container** when you want:

* **Per-widget local behavior**
  * A single card that can expand/collapse without affecting others
  * A like/favorite toggle on each item in a list
  * A per-item counter (e.g., quantity selector in a cart row)
* **Isolated UI state**
  * Tabs, steps, or internal view toggles inside one section
  * Local selection in a small segment (e.g., chip group, filter section)
  * Temporary UI flags like `isLoading`, `isExpanded`, `isEditing` for one block
* **Repeated widgets with independent state**
  * Multiple cards, each with its own `isOpen`, `count`, or `selected`
  * Reusable components that should **not share** state with other instances