Field Relationships & Dependencies

Dependencies define dynamic relationships between form fields. They control field visibility, validation rules, available options, and data binding based on other field values.

Overview

Field dependencies enable powerful interactions like:

• Conditional visibility: Show/hide fields based on other field values
• Dynamic options: Load dropdown options from APIs or other fields
• Cascading selections: Changes in one field update another
• Conditional validation: Apply different rules based on field values
• Property updates: Dynamically change field properties like placeholder, disabled state, etc.

Dependency Types Quick Reference

When to Use Each Type

1. exists - Conditional Field Display

Best for: Show/hide entire fields based on conditions

When to use:

• Optional fields that depend on earlier choices
• Complex forms with many optional sections
• Progressive disclosure of form fields

Example - Show Address Fields:

{
  "name": "shippingAddress",
  "meta": {
    "displayName": "Shipping Address",
    "displayType": "text",
    "dependencies": {
      "exists": {
        "ref": "usesDifferentShipping",
        "value": true
      }
    }
  }
}

Real-world example: E-commerce checkout - show tax ID field only if "Business Account" is checked.

2. equals - Conditional Field Enabling

Best for: Enable/disable based on exact value match

When to use:

• Toggling dependent fields on/off
• Required acknowledgments before proceeding
• Mutual exclusivity between options

Example - Enable Confirmation Field:

{
  "name": "confirmChanges",
  "meta": {
    "displayName": "I confirm these changes",
    "displayType": "checkbox",
    "dependencies": {
      "equals": {
        "ref": "acceptTerms",
        "value": true
      }
    }
  }
}

3. enabled - Reference Field value

Best for: Enable/disable based on reference field's value

When to use:

• Fields that depend on parent field being interactive
• Multi-step workflows
• Permission-based field access

For example: Employee status form

Employer name is enabled only if the employee is employed

4. options - Cascading Select Options

Best for: Populate one select based on another select's value

When to use:

• Country → State hierarchies
• Category → Product hierarchies
• Parent → Child relationships

Example - Country to State Cascade:

[
  {
    "name": "country",
    "meta": {
      "displayName": "Country",
      "displayType": "select",
      "options": [
        { "label": "United States", "value": "US" },
        { "label": "Canada", "value": "CA" }
      ]
    }
  },
  {
    "name": "state",
    "meta": {
      "displayName": "State",
      "displayType": "select",
      "options": [
        { "label": "California", "value": "CA", "ref": "US" },
        { "label": "Texas", "value": "TX", "ref": "US" },
        { "label": "Ontario", "value": "ON", "ref": "CA" }
      ],
      "dependencies": {
        "options": { "ref": "country" }
      }
    }
  }
]

5. value - Dependent Field Values

Best for: Set one field's value when another field changes

When to use:

• Store hidden IDs or metadata from a selected option
• Auto-fill a read-only field from another field
• Compute a simple derived value through a registered valueFn

Example - Store Selected Country ID:

{
  "name": "country_id",
  "meta": {
    "displayType": "hidden",
    "dependencies": {
      "value": {
        "ref": "country",
        "valueKey": "id"
      }
    }
  }
}

6. propUpdate - Conditional Property Changes

Best for: Dynamically update field properties

When to use:

• Change labels based on context
• Change placeholder text dynamically
• Toggle field attributes (required, disabled, etc.)

Example - Change Label Based on User Type:

{
  "name": "companyName",
  "meta": {
    "displayName": "Your Organization",
    "displayType": "text",
    "dependencies": {
      "propUpdate": {
        "ref": "userType",
        "propName": "displayName",
        "valueMap": {
          "individual": "Optional: Business Name",
          "business": "Company Name (Required)",
          "nonprofit": "Organization Name"
        }
      }
    }
  }
}

7. patternMatchUrlLoader - Advanced API Integration

Best for: Call API and update field based on URL pattern matching

When to use:

• Auto-populating forms from URL parameters
• Deep linking with data hydration
• Marketing campaign URL handling

Advanced: Condition Objects

For complex dependencies, use condition arrays:

type Condition = [Operand, Operator, Value, NextCondition?];
 
Operators: "===" | ">=" | "<="
 
NextCondition: "||" | "&&"

Example - Show field if (Country="US" AND State="CA") OR (Country="MX"):

{
  "dependencies": {
    "exists": {
      "value": "$condition",
      "condition": [
        [
          { "ref": "country" },
          "===",
          "US",
          "&&"
        ],
        [
          { "ref": "state" },
          "===",
          "CA"
        ],
        "||",
        [
          { "ref": "country" },
          "===",
          "MX"
        ]
      ]
    }
  }
}

Best Practices

✅ DO:

• Use exists for major conditional sections
• Test cascading dependencies with different values
• Keep condition logic simple and readable
• Use lazy loading for large option lists
• Document complex dependencies with comments

❌ DON'T:

• Nest too many dependencies (avoid "dependency hell")
• Create circular dependencies between fields
• Use propUpdate for complex calculations
• Hardcode user-specific data in dependencies

Detailed Documentation by Type

Explore each dependency type in detail:

• exists - Conditional Display →
• options - Cascading Options →
• value - Dependent Field Values →
• propUpdate - Property Changes →

Common Patterns

Properties

Troubleshooting Dependencies

Performance Tips

• Lazy load options: Use config.lazy: true for select fields
• Minimize API calls: Batch dependent fields that call the same API
• Cache results: Ask backend to cache frequently accessed lists
• Debounce searches: For searchable selects, add debouncing in config

More Examples

• Products Cascade →
• Registration Form →
• Customer Feedback Form →
• Salaried Form →