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.

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

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

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