Back to Wizard Flow

Documentation

VARIABLES

Variable Accumulation System

The Variable Accumulation System enables data to flow through your entire wizard journey, creating personalized and dynamic user experiences.

Table of Contents

Overview

Variables allow you to:

  • Store field values with semantic names
  • Access data across all wizard pages
  • Personalize content with user data
  • Create dynamic conditional logic
  • Build calculated values

Key Concepts

Variables vs Answers

Answers - Raw form data stored by field ID

  • Format: answers.field_id
  • Scope: Single field reference
  • Example: answers.age_field
Variables - Named accumulated data
  • Format: variables.variableName
  • Scope: Available throughout wizard
  • Example: variables.userAge

Setting Up Variables

1. Field-Level Variables

Add a variableName property to any field:

json
{
  "id": "name_field",
  "type": "text",
  "label": "Your Name",
  "required": true,
  "variableName": "userName"
}

2. Global Variables

Define calculated variables at the flow level:

json
{
  "variables": [
    {
      "id": "isAdult",
      "expr": "answers.age >= 18"
    },
    {
      "id": "bmi",
      "expr": "answers.weight / ((answers.height / 100) * (answers.height / 100))"
    }
  ]
}

Using Variables

In Conditions

Use variables in edge conditions for navigation:

json
{
  "edges": [
    {
      "when": "variables.userAge >= 18",
      "to": "adult_page"
    },
    {
      "when": "variables.userAge < 18",
      "to": "minor_page"
    }
  ]
}

In Visibility Rules

Control field visibility based on variables:

json
{
  "id": "senior_discount",
  "type": "checkbox",
  "label": "Apply senior discount",
  "visibility": "variables.userAge >= 65"
}

In Validations

Use variables in validation expressions:

json
{
  "validation": [
    {
      "type": "custom",
      "expression": "value <= variables.budgetMax",
      "message": "Amount exceeds your budget"
    }
  ]
}

Template Syntax

Basic Substitution

Use double curly braces for variable substitution in text:

json
{
  "title": "Welcome {{variables.userName}}!",
  "description": "Hi {{variables.firstName}}, let's continue with your application."
}

Where Templates Work

Templates are processed in:

  • Page titles
  • Page descriptions
  • Group titles
  • Group descriptions

Template Examples

json
{
  "pages": [
    {
      "id": "summary",
      "title": "Summary for {{variables.userName}}",
      "description": "Your BMI is {{variables.bmi}} and you exercise {{variables.exerciseDays}} days per week."
    }
  ]
}

Debug Panel

Enabling Debug Mode

The debug panel helps you track variable values during development.

#### In Preview Mode

  • Click "Preview" in the editor toolbar
  • Toggle "Show Debug" checkbox in the preview header
  • Debug panel appears on the right side

    • #### Features

    • Variable Section: Shows all accumulated variables
    • Answers Section: Shows raw field answers
    • Collapsible: Click headers to expand/collapse
    • Live Updates: Values update as you progress

    Debug Panel Layout

    shell
    ┌─────────────────────────┬──────────────┐
│                         │              │
│     Wizard Content      │  Debug Panel │
│                         │              │
│                         │  Variables:  │
│                         │  - userName  │
│                         │  - userAge   │
│                         │              │
│                         │  Answers:    │
│                         │  - field_1   │
│                         │  - field_2   │
└─────────────────────────┴──────────────┘

    Examples

    Personal Information Collection

    json
    {
  "pages": [
    {
      "id": "personal_info",
      "title": "Personal Information",
      "fields": [
        {
          "id": "first_name",
          "type": "text",
          "label": "First Name",
          "variableName": "firstName"
        },
        {
          "id": "last_name",
          "type": "text",
          "label": "Last Name",
          "variableName": "lastName"
        },
        {
          "id": "age",
          "type": "number",
          "label": "Age",
          "variableName": "userAge"
        }
      ]
    },
    {
      "id": "greeting",
      "title": "Hello {{variables.firstName}}!",
      "description": "Welcome {{variables.firstName}} {{variables.lastName}}, let's continue.",
      "fields": []
    }
  ]
}

    Conditional Navigation with Variables

    json
    {
  "pages": [
    {
      "id": "age_check",
      "fields": [
        {
          "id": "age",
          "type": "number",
          "label": "Your Age",
          "variableName": "userAge"
        }
      ],
      "edges": [
        {
          "when": "variables.userAge >= 18 && variables.userAge < 65",
          "to": "adult_content"
        },
        {
          "when": "variables.userAge >= 65",
          "to": "senior_content"
        },
        {
          "when": "variables.userAge < 18",
          "to": "youth_content"
        }
      ]
    }
  ]
}

    Calculated Variables

    json
    {
  "variables": [
    {
      "id": "fullName",
      "expr": "answers.firstName + ' ' + answers.lastName"
    },
    {
      "id": "isEligible",
      "expr": "answers.age >= 21 && answers.hasLicense === true"
    },
    {
      "id": "discountRate",
      "expr": "answers.memberType === 'premium' ? 0.20 : 0.10"
    }
  ]
}

    Best Practices

    Naming Conventions

    • Use camelCase for variable names: userName, userAge
    • Be descriptive: customerEmail not email
    • Group related variables: addressStreet, addressCity, addressZip

    Performance

    • Only create variables for data used across pages
    • Use field IDs for single-page references
    • Avoid complex calculations in frequently evaluated expressions

    Organization

    • Group related fields with similar variable prefixes
    • Document variable purpose in field descriptions
    • Use consistent naming across your wizard

    Data Types

    Variables maintain their field type:

    • Text fields → String variables
    • Number fields → Number variables
    • Checkbox fields → Boolean variables
    • Select/Radio → String/Number based on option values

    API Reference

    Field Interface

    typescript
    interface Field {
  id: string;
  type: FieldType;
  label: string;
  variableName?: string;  // Optional variable name
  // ... other properties
}

    Variable Interface

    typescript
    interface Variable {
  id: string;           // Variable name
  expr: string;         // Expression to evaluate
  defaultValue?: any;   // Default if expression fails
}

    WizardState Interface

    typescript
    interface WizardState {
  answers: Record<string, any>;    // Field ID → Value
  variables: Record<string, any>;  // Variable Name → Value
  // ... other properties
}

    Expression Context

    Variables are available in the expression evaluation context:

    typescript
    interface EvaluationContext {
  answers: Record<string, any>;
  variables: Record<string, any>;
  page?: Page;
  field?: Field;
}

    Troubleshooting

    Variables Not Updating

    • Ensure field has variableName property
    • Check for typos in variable names
    • Verify expression syntax is valid

    Template Not Rendering

    • Use correct syntax: {{variables.name}}
    • Ensure variable exists before referencing
    • Check that template processing is enabled for that field type

    Debug Panel Not Showing

    • Toggle "Show Debug" checkbox in preview
    • Ensure you're in preview mode, not edit mode
    • Check browser console for errors

    Migration Guide

    Adding Variables to Existing Wizards

  • Identify fields that need cross-page access
  • Add variableName to those fields
  • Update conditions to use variables.name instead of answers.fieldId
  • Add template placeholders for personalization
  • Test with debug panel enabled

    • Backward Compatibility

    • Existing wizards work without modification
    • answers.fieldId references continue to work
    • Variables are opt-in per field
    • No breaking changes to existing flows

    Related Documentation

    © 2026 Jonathan Leahy · v1.0.11