State

State manages the data within Jigx solutions, jigs, and components and controls the UI dynamically. The state allows solutions and components to change their output in response to user inputs and actions. Often, the state is used as a global variable that can be used throughout the solution or as a local state used only in that specific jig or component.

Examples of using state include:

• Displaying a list of items that change based on user interaction.

• Handling user inputs in forms, such as text inputs or switches. By storing input values in the state, you can easily control the components and validate user input.

• Control the behavior of components, like showing or hiding a component based on a condition, enabling or disabling buttons or fields, and resetting a component's value.

• State is local to the jig or component where it is declared; you can share the state across multiple jigs and their components or use a global state across the entire solution.

State allows you to read and write the state of various data in your solution at runtime.

Whenever working with data, consider the performance impact on the Jigx App at runtime. The best practice is to write only the required data in the state and consider using state versus inputs and outputs.

Using states in Jigx is divided into categories:

1. Global state - known as solution state in Jigx, refers to data that needs to be accessed and updated by multiple components across the app. Effectively managing the global state ensures that all parts of the app that depend on this data are updated consistently. The global/solution state is a variable used throughout the solution.

2. Local state - known as component state in Jigx, refers to data that is confined to a single component or jig. This type of state is typically managed within the component itself. The creator can set each component state in the YAML or by user input, such as a text field. The state key options depend on the component.

3. State navigation allows you to determine the flow of screens and the state of each one in the flow. See Navigation for more information.

State scopes & performance

Decision Tree

Use the decision tree below to guide you through the process of selecting the most appropriate state management scope and approach for application components, helping determine whether to use local component state, shared state, or global state management solutions based on data usage patterns and component relationships.

Need data across multiple screens? 
├─ YES → solution.state (USE SPARINGLY - causes app-wide re-render)
│  └─ Examples: projectId, auth session, theme
└─ NO → Screen-specific data?
   ├─ YES → jig.state (PREFERRED - screen-local, performant)
   │  └─ Examples: search filters, form flags, selection
   └─ NO → Component input/validation?
      └─ YES → component.state (automatic - user input, validation)
         └─ Examples: form values, isDirty, isValid

Performance Impact Table

Scope	re-render impact	Use when	Avoid when
solution.state	Entire app	Authorization Global selections that rarely change	UI filters Form state Temporary flags
jig.state	Current screen	Screen filters Selection, Wizard progress	Cross-screen data Component values
component.state	Single component	User input Validation	Cross-component data Screen logic

Performance best practice

• Scope Minimization: Use narrowest scope (component → jig → solution)

• Avoid Global Overuse: solution.state triggers app-wide re-render, prefer jig.state over solution.state

• Initialize Explicitly: Always set initialValue to avoid undefined behavior

• Clean Up: Reset transient state after actions/navigation

• Pass vs Store: Prefer navigation parameters over state storage

• Passing data: Pass data via parameters, not state

• Clear state: on refresh/navigation

State syntax

States vary based on the context in which they are used. Use IntelliSense in expressions to determine where you can make use of states. IntelliSense can assist by directing you to the context tree, showing which states are available for use within the context of the jig.

Avoid using state keywords, such as component, as instanceId values in expressions. Doing so will cause an "Expression is not valid" error in the app.

Solution (Global) State

Syntax	Key	Area
[email protected].	activeItem key now	Global variable used throughout a solution. Your variable that can be set and read.

Jig (local) State

Syntax	Key	Area
[email protected].	activeItem activeItemId amounts filter isHorizontal isRefreshing isSelectable isSelectActive searchText selected value	Applies to a list jig. The creator configures the state in the YAML.
[email protected]		Used to push the jig instance (state) to the navigation stack.

Component (local) State

Syntax	Key	Area
[email protected].jigInstanceId.components.componentInstanceId.state.	data isDirty isValid response	Read the state of a component in a specific jig using the instanceId of both the jig and component. Referencing components on a composite jig.
[email protected].	amount checked selected value	State is the variable of /or for each component.
[email protected].	data filter isValid isDirty isPending searchText selected response value	State of components, using the component's instanceId. Can use interaction from the user to add a value to the component's state, such as email-field, text-field, or number-field.
[email protected].	amount checked	Applies to a list, list.item, product-item, and stage components. The list's data is an array of records. The [email protected] is the state of the current object in the array.

State Lifecycle

Lifetime

• solution.state: in-memory; cleared on logout (app-wide re-render on change).

• jig.state: per jig instance; persists while on navigation stack; resets on new instance.

• component.state: per component; cleared when navigating away from jig.

Initialization

// ✅ Always use initialValue
jig.setState({ 
  searchQuery: { initialValue: '' },
  filters: { initialValue: { category: 'all' } },
  selected: { initialValue: [] }
})

Navigation

Cleanup

State Core operations

Initialize state

• Sets up the initial state structure when the screen loads

• Defines default values to avoid undefined errors

• Creates the state "schema" for your screen

state:
  StateKey1: 
    # String
    initialValue: 
      value: string
  StateKey2: 
    # Array
    initialValue: 
      - one
      - two
      - three
  StateKey3:
    # object
    initialValue:
      - property: value

Update state

• Updates only the specified state key

• Triggers re-render only for components that use that state

• Can chain multiple state changes

• Works with expressions and static values

solution

actions:
- numberOfVisibleActions: 1
  children:
    - type: action.reset-solution-state
      options:
        changes:
          - StateKey1

jig/screen

component

Clear state

• Resets specified keys back to their initialValue

• Can reset multiple keys at once

• Useful for cleanup and form resets

solution

actions:
- numberOfVisibleActions: 1
  children:
    - type: action.reset-solution-state
      options:
        changes:
          - StateKey1
          - StateKey2
          - StateKey3

jig/screen

component

How to use State

Solution state (global read and write state)

You can define your solution state to store objects and values temporarily and then read them in multiple places in your solution. These are not stored in any local or remote data store but only in live memory. If you log out your solution state is cleared.

• Configure the initial solution state in the index.jigx file by providing a State Key with a value.

• You can update the state using the action.set-solution-state action.

• To revert back to the initial state, simply use the action.reset-solution-state action.

• Multiple states can be added in index.jigx and initialValues support nested objects, strings, and arrays.

• To call nested objects in a state expression use: [email protected]

Write solution state

Define your state key in the solution, either in a jig or in the index.jigx file. The value can be any value or object, and you can access it anywhere within your solution. The set-solution-state action are easy ways to define the solution state.

Read solution state

To access your custom solution state, use the expression path below and replace [key] with your custom solution state key.

1. [email protected].[key].

2. For nested objects use [email protected].

index.jigx

name: Projects
title: Global Projects
category: business
# Solution state's initial key values.
state:
  project:
    initialValue:
      # Nested objects
      status: "Active"
      team: "Planning team"
  Billing:
    initialValue: "Monthly"

action.set-solution-state (Write)

action.reset-solution-state (Write)

Read state value

Jig state (read and write state)

Defines the state [key] for the jig/screen that can be read from within the current jig.

• Configure the initial jig state in the desired jig file.

• In any jig, you can update the state using the action.set-jig-state action.

• To revert back to the initial state, simply use the action.reset-jig-state action.

• Multiple states can be added and initialValues support nested objects.

• To call nested objects in a state expression use [email protected]

Within the jig

Reads the value in the jig's context (the jig where the expression is used), for example: @ctx.jig.state.[key]

Define your state key in the jig file. The value can be any string, array, or object, and you can access it anywhere within the jig. The set-jig-state action is an easy way to define the jig state and reset-jig-state action sets the state back to the initial key values.

jig-initial-state.jigx

title: Global Inc
description: Welcome to Gobal Inc
type: jig.default
# Configure the initial jig state key values.
state:
  predefinedtext:
    initialValue: "Committed to excellence and innovation"
  address:
    initialValue:
      street: 145 Morrissey Blvd
      city: Boston
      zip code: O2125

action.set-jig-state (write)

action.reset-jig-state (write)

jig-a.jigx (read)

Component state (read state)

Define your state [key] for a single component or all components in a jig. Navigating away from the jig clears your component's state as the data is stored in the live memory.

Within the current component

Reads the value of [key] in the current component (the component where the expression is used), for example: [email protected].[key]

Within all components in the current jig

Reads the value of [key] in the current jig and components with instanceId, for example:[email protected].[instanceId].state.[key]

Within all jigs and components in the solution

Reads the value of [key] from the available jigs with jigId and components with instanceId. For example: [email protected].[jigId].components.[instanceId].state.[key]

Action state (write state)

You can use actions to set (update) or reset (clear) a state either in a solution, jig, or component. These actions can be configured under the actions node or under an event node, such as onPress.

The following set-state actions are available:

• action.set-state

• action.set-solution-state

• action.set-jig-state

• action.set-custom-component-state

The following reset-state actions are available:

• action.reset-state

• action.reset-solution-state

• action.reset-jig-state

• action.reset-custom-component-state

The only difference between these states are the scope where they are used. See the table below.

Action	Solution	Jig	Component	custom component (alpha)
action.set-state	✅		✅
action.reset-state	✅		✅
action.set-solution-state	✅	✅		✅
action.reset-solution-state	✅	✅		✅
action.set-jig-state		✅		✅
action.reset-jig-state		✅		✅
action.set-custom-component-state				✅
action.reset-custom-component-state				✅

Setting a state using an action (set-states)

The basic set-state actions code structures are shown below:

set-solution-state-action

# Set the solution state keys to new values.
actions:
  - children:
      - type: action.set-solution-state
        options:
          title: Update state
          changes:
            # state key.
            status: "InActive"

set-jig-state-action

set-state-action

Reset a state using an action (reset-states)

The basic reset-state actions code structures are shown below:

reset-solution-state-action

# Reset the solution state keys to the initial values.
actions:
  - children:
      - type: action.set-solution-state
        options:
          title: Update state
          changes:
            status: "InActive"

reset-jig-state-action

reset-state-action

Setting a state on an event using an action

You can use the set-states or reset-states actions with the following events:

• onFocus

• onLoad

• onPress

• onRefresh

• onChange

onFocus-set-solution-state

onFocus:
  type: action.set-solution-state
  options:
    changes:
      status: [email protected][0].mottos

Action state patterns

Async Operations

// ✅ Pattern: Action states are automatic
buttons.add.executeEntity({ instanceId: 'save-action' })

// Read states
spinner.isVisible('[email protected]')
successMsg.isVisible('[email protected]')
errorMsg.text('[email protected]')

// Access outputs
detailText.value('[email protected]')

Loading States

Quick Validation

# State exists check
when: [email protected] != null and @ctx.jig.state.searchQuery != ''

# Type safety  
when: [email protected] ~> $type = 'number'

# Default values
text: [email protected] ?: 'Default Title'

Common state use cases (patterns)

• Search & Filter Mirrors UI state to bind to datasource Filter: [email protected] Query parameter: [email protected]

• List Selection Tracks selection in jig.state The onPress action uses the selectedId of [email protected] Once selected uses isSelected of the [email protected] in [email protected]

• Field Validation Real-time validation with errorText

email-field

errorText: [email protected] = false ? "Invalid email format" : null

text-field

number-field

• Form Dirty Tracking Track changes for discard alert. - Set jig state formIsDirty: initialValue: false - onFocus set jig state and change formIsDirty: true - On the form isDiscardChangesAlertEnabled use [email protected]

Examples of state

The table below provides links to various examples of configuring state in the jigx-samples.

Scenario	Key	GitHub jigx-samples examples
Set an item to active with onPress	ActiveItemId	List with active items
searchText (component level)	searchText	Dropdown with search
filter and searchText (jig level)	filter, searchText	List with filter and search
Saving data to a provider	value	Update service form
Evaluating an amount	amount	Product item maximum tag
Evaluating if an item is selected	checked	Highlight selected list of cleaning services
Evaluating selected items	selected	Evaluate progress to show helper and error text
Reset a form	reset-state (action)	Reset a form
Set state on an active item in a list when the onPress event executes	set-state (action)	Color a chosen item when pressing on an item in a list

See Also

• set-state

• reset-state