Variable

Overview

A Variable is a Resource that holds a value that can change as users interact with your Dynamic Component. Use a Variable when a value needs to be read, updated, or written to during the component's lifecycle — filters, form inputs, toggles, Flow outputs, Agentforce responses, or structured data passed between components.

Unlike a Constant (which never changes) or a Formula (which is computed), a Variable is the only Resource type you can actively write to.

JSON Data Type

The JSON data type lets a Variable hold structured data — a single object, a collection, or a nested hierarchy — and bind that shape directly to your components. Before JSON, modeling anything beyond simple inputs meant flattening data into a dozen text and number variables, or pushing the work into Apex. JSON Variables let you keep the original shape and reference it where you need it.

When to use JSON

Reach for JSON when:

The data comes from outside your component — a Flow output, an Agentforce response, an Apex-defined type, or an external API.
You need to feed a collection to a data-aware component (Data Table, Kanban, List, Map, Repeater, Carousel, Chart).
The structure is hierarchical and you want to drill into nested fields directly.

Stick with Text, Number, or Boolean when a single scalar value will do, or when the value never crosses the boundary out of your component.

Here's what becomes possible.

Pipe a Flow's Apex-defined output straight into your UI

Your Flow returns a list of opportunities with their related contacts and last activity. A JSON Variable captures the entire shape and feeds it into a Data Table without a line of code. Will the Apex output structure change next sprint? Update the Variable and rebind. No rewrite

Capture what Agentforce gives back and display it

An agent action returns a structured recommendation: top 3 accounts to call today, with reasons and suggested next steps. Store the response in a JSON Variable, then drop a List, a Kanban, or a custom card layout on top to render it. Your component now reacts to AI output as fluidly as it reacts to a click

Build a record on the fly without a Salesforce object

A multi-step wizard collects company info, contacts, and product preferences across five screens. Instead of juggling fifteen flat variables, assemble one JSON Variable that grows as the user moves through the flow. At the end, send the full object to Apex, MuleSoft, or a webhook — already shaped the way the receiver expects

Use a JSON collection as a Data Source

Load a list once — the result of a callout to a pricing API, a curated list of strategic accounts, the output of an Agentforce action — store it in a JSON Variable, and point a Data Table, Kanban, Map, or Repeater at it. The collection becomes a reusable source any data-aware component can read from, with no new Salesforce object and no Apex

Hold a shopping cart, a filter context, or any working state

A guided selling experience requires a cart that includes line items, quantities, totals, and applied promo codes. A complex filter panel needs to pass twelve criteria to a query at once. A dashboard needs to remember which tabs are expanded and which rows are selected. JSON Variables hold all of this in a single named shape that any component on the canvas can read or write

Mock the data while you build the rest

Waiting on the backend team to expose the right SOQL or REST endpoint? Drop the expected payload into a JSON Variable as a placeholder, build the entire UI against it, then swap the Variable's source for the real call when it's ready. The components downstream don't know the difference.

Assemble exactly the payload an external system expects

Some endpoints want their input shaped in a specific way — nested objects, arrays of arrays, renamed fields, formatted dates. JSON Variables let you compose that exact structure through Assignment interactions, then hand it off to Apex, a Flow, or a callout with no translation layer in between

The pattern across all of these is that the JSON Variable serves as the shared memory between your UI, your data sources, and whatever sits on the other side of the page. Anything that has shape can now live inside your component

JSON vs Record

Both can hold a Salesforce record. Pick Record when you only need a reference (an Id) that other parts of the component can resolve. Pick JSON when you want the actual field values in hand — Name, Industry, custom fields, related records — without an extra Salesforce roundtrip.

Quick Start: Build a Region Filter in 2 Minutes

Create a Variable to hold the user's selected region, and use it to filter a Data Table.

Create the Variable

Click the Resources button to open the Resources panel.
Click New Resource, then choose Variable.
API Name: selectedRegion
Data Type: Text
Default Value: North America
Click Save.

The default makes the filter work on first load before the user picks anything.

Add a Combobox to capture the user's choice

Drag a Combobox onto the Canvas.
In the Properties Panel, set Options to a Manual list with North America, EMEA, APAC.
Set Value to {!selectedRegion} so the Combobox reads from the Variable.

Wire the Combobox to update the Variable

With the Combobox selected, open the Interactions tab.
Add an interaction on the Change trigger.
Action: Assignment.
Target: selectedRegion Variable.
Operator: Equals.
Value: {!Component.Value} — the new Combobox value.

Filter a Data Table by the Variable

Drag a Data Table onto the Canvas.
Configure its Data Source as a Query on the Account object.
Add a filter: Field BillingCountry, Operator Equals, Value {!selectedRegion}.
Save and Deploy.

The Data Table now refreshes whenever the user changes the Combobox.

Creating a Variable

To create a Variable in the Component Builder:

Open the Resources panel.
Click New Resource, then select Variable.
Fill in the configuration fields described below.
Click Save.

Setting

Description

Example / Options

API Name

Unique identifier used to reference the Variable. Must start with a letter and contain only alphanumeric characters and underscores.

selectedRegion, currentUser, searchResults

Description

Optional note about the Variable's purpose. Visible in the Resources panel.

"Holds the region selected by the user"

Data Type

The kind of value the Variable holds. See Data Types.

Text, Number, Boolean, Date, Date/Time, Record, JSON

Allow multiple values (collection)

Stores multiple values of the same type as an ordered list.

Default: off

Default Value

Initial value the Variable holds before any interaction writes to it. Hidden for JSON Variables — set defaults in the Structure Editor instead.

North America, 42, true

Decimal Places

(Number type only) Digits after the decimal point.

2

Availability Outside of this Dynamic Component

Exposes the Variable as an input or output for Flows and Agentforce.

Input, Output, Both

Naming Variables

Use API names you will recognize months later. Avoid generic names like var1, data, temp, or result — they help no one when you (or a teammate) revisit the component to extend it.

Good: selectedRegion, enrichedAccounts, isApproved, currentUser. Avoid: var1, myVar, temp, data2.

Data Types

Data Type

Use For

Example Value

Text

Strings, IDs, single-line text

"Acme Corp"

Number

Integers and decimals

42, 3.14

Boolean

True/false flags

true

Date

Date without time (ISO 8601)

2026-04-21

Date/Time

Date with time and timezone (ISO 8601)

2026-04-21T14:30:00Z

Record

A reference to a Salesforce record by Id

0014x00000XYZab

JSON

Structured data — records, collections, nested objects

{"name": "Acme", "industry": "Tech"}

Any data type can be converted to a Collection by checking Allow multiple values. A collection holds multiple values of the same type in an ordered list — a collection of Text holds an array of strings, a collection of JSON holds an array of records.

JSON Structure Editor

When you set a Variable's data type to JSON, the Structure Editor opens so you can define the shape of the value the Variable holds.

The Structure Editor is a tree where each node represents a field in your JSON object. The values you set on each node become the Variable's default value — there is no separate Default Value field for JSON Variables.

Supported Node Types

Node Type

Holds

Notes

String

Text

Use for IDs, labels, free text

Number

Numeric value

Integers or decimals

Boolean

True/false

Renders as a toggle in the editor

Object

Nested structure with its own children

Build hierarchies of any depth

Array

An ordered list of items

Items inside follow the same node types

Example Structure

A currentUser Variable holding a user record:

currentUser (Object)
- id (String) — "005xx0000012345"
- name (String) — "Cedric Verge"
- email (String) — "[email protected]"
- isActive (Boolean) — true
- region (Object)
  - country (String) — "France"
  - timezone (String) — "Europe/Paris"

You can then reference any path inside the structure: {!currentUser.email}, {!currentUser.region.country}, and so on.

JSON Collections

Setting Allow multiple values on a JSON Variable creates a JSON Collection — an array of objects matching the structure you defined. JSON Collections are the foundation for feeding records to data-aware components such as Data Table, Kanban, List, Map, Repeater, Chart, and Carousel.

Limits and Behavior

No hard cap on depth or array size, but render time degrades as collections grow. For lists above a few hundred items, paginate at the source (Apex, Flow, query) rather than loading everything into a single JSON Collection.
Field names are case-sensitive. Email and email are two different paths. Match the casing of whatever populates the Variable (Apex type, Flow output, API response).
Missing paths return empty. A reference to {!user.email} resolves to empty if the path doesn't exist or the field is unset — it does not throw, which makes typos easy to miss. Confirm with the Debug Panel.

Variable Availability

The Availability Outside of this Dynamic Component setting controls whether a Variable can be read or written from outside the component — by Flows, Agentforce, or the Lightning Page that hosts the component.

Availability

What It Does

Input

The Variable accepts a value from outside. Set by a Flow input, an Agentforce parameter, or a Lightning Page property.

Output

The Variable's value is exposed to outside callers. Read by a Flow output, an Agentforce response, or another component.

Both

The Variable accepts an input value and exposes its current value as an output.

Availability is only configurable for non-collection Variables.

Using a Variable

Once a Variable exists, you can reference it anywhere a dynamic value is accepted — filter values, component defaults, formula expressions, interaction inputs, visibility conditions.

Inserting a Reference

Open the property where you want the Variable's value.
Click the resource selection icon next to the field.
Pick the Variable from the list.

The reference is inserted automatically, wrapped in curly braces.

Reference Syntax

Two reference styles exist because they resolve at different scopes:

{!variableName} resolves at the component level. Use this everywhere except inside a loop.
{{Record.field}} resolves inside the loop scope of a Repeater or List bound to a JSON Collection. Record refers to the currently rendered item.

Syntax

Use Case

Example

{!variableName}

Reference the full Variable value

{!selectedRegion}

{!variableName.path.to.field}

Drill into a JSON Variable's nested path

{!currentUser.region.country}

{{Record.field}}

Reference the current item inside a loop bound to a JSON Collection

{{Record.email}}

Feeding a Data-Aware Component from a JSON Collection

A JSON Collection Variable can be used directly as a component's Data Source.

Drag a data-aware component onto the Canvas (Data Table, List, Kanban, Map, Repeater, Chart, etc.).
In the Properties Panel, set Data Source to Variable.
Pick your JSON Collection Variable from the list.
Map the component's fields to paths inside the Variable's structure.

Assigning Values to a Variable

Variables are written to in three ways: through Assignment Interactions, by Flow outputs, and by Agentforce responses.

Assignment Interaction

The most common way to update a Variable is through an Assignment Interaction triggered by a user action— such as — a button click, a value change, or a row selection.

Select the component that triggers the assignment.
Open the Interactions tab.
Add an interaction on the relevant trigger.
Choose Assignment as the action.
Pick the target Variable, choose an operator, and supply the value.

Operators by data type:

Data Type

Operators

Text

Equals, Add (concatenate), Replace, Replace All, Replace by Regex

Number

Equals, Add, Subtract

Boolean

Equals, Toggle

Date / Date/Time

Equals, Add (days), Subtract (days)

JSON

Equals (full replacement of the Variable's value)

Updating a Single Field of a JSON Variable

JSON only supports Equals, which replaces the entire Variable value. To update one field while preserving the rest, you have three options:

Build the full structure in the assignment value. Type the JSON object literally, referencing the existing fields you want to keep. Example: assign {"name": "{!currentUser.name}", "email": "{!Component.Value}", "isActive": {!currentUser.isActive}} to update only the email.
Use a Formula Resource to compose the new structure and reference the Formula in the assignment value. Cleaner when the object has many fields.
Push the update through a Flow. The Flow receives the current Variable as input, modifies the field, and returns the updated structure. Best for objects with many fields or complex logic.

Adding or Removing Items in a JSON Collection

There is no built-in operator to push or splice an item into a JSON Collection. Use a Flow that receives the current collection and the new item as inputs, performs the array operation in Flow logic, and returns the updated collection. Map the Flow output back to your Variable.

Sorting and Filtering a JSON Collection

To sort or filter a JSON Collection without going back to the source, use a Formula Resource to derive a transformed collection, then bind your component to the Formula instead of the raw Variable. This keeps the original data intact while letting you render a different view of it.

Flow Output

Variables marked as Input can receive values from a Flow's output.

Configure a Flow Builder Integration interaction on the component.
After the Flow runs, map its output variables to your Dynamic Component Variables in the Output Variables section.
Apex-defined Flow outputs map cleanly into JSON Variables — the JSON structure must match the Apex type's field names and types, character for character.

Apex to JSON Variable: Field Mapping

Given this Apex type returned by a Flow:

public class AccountSummary {
    @AuraEnabled public String accountId;
    @AuraEnabled public String name;
    @AuraEnabled public Decimal annualRevenue;
    @AuraEnabled public Boolean isCustomer;
}

Build the JSON Variable structure as:

summary (Object)
- accountId (String)
- name (String)
- annualRevenue (Number)
- isCustomer (Boolean)

Field names are case-sensitive. accountId ≠ accountID ≠ AccountId. Mismatches resolve to empty without raising an error, which makes them easy to miss — start with the Debug Panel to confirm the structure populates.

Agentforce

Variables marked as Input can be written to by Agentforce responses. JSON Variables are particularly useful for capturing structured agent output that includes multiple fields or a list of records.

Example: Capture an Agent's Lead Recommendations

An Agentforce action returns a list of recommended leads with a score and a reason for each.

Create a JSON Variable recommendedLeads with Allow multiple values checked.
Build the Structure: id (String), name (String), score (Number), reason (String).
Set Availability to Input.
In the Agentforce action configuration, map the agent's response fields to the corresponding paths in recommendedLeads.
Bind a List or Data Table on the Canvas to the Variable to render the recommendations.

Debug Panel

The Debug Panel on the right side of the Component Builder preview lets you inspect and modify Variable values without leaving the builder.

Tab

What It Shows

Variables

Input Variables (editable inline) and Output Variables (read-only, show current runtime value)

Formulas

The current computed value of every Formula Resource

Click Save in the Debug Panel to persist the current Variable values as the debug defaults — useful for testing the same scenario across sessions.

Testing JSON Variables

For JSON Variables, the Debug Panel accepts raw JSON. Paste a sample payload (an Apex response, an Agentforce output, an API response) directly into the Variable's value field to test how your component renders it. This is the fastest way to validate your structure matches the source before wiring up the real data path.

Data Persistence: The Reset

Variable values reset when Salesforce performs a DML operation triggered by your component — Create, Update, Delete, or Upsert. This is intentional: after the database changes, the component re-reads its data to stay in sync, and Variables go back to their default values.

Workarounds

If you need a value to survive a DML operation:

Re-assign the value after the DML — chain an Assignment Interaction after the Save action.
Store the value outside the component — write it to the underlying Salesforce record, or pass it through a Flow that persists it.
Use a Constant if the value never needs to change.

Under the Hood

After a DML, the component reloads its Data Sources and resets its Variables to their defaults (or to the values captured by the Debug Panel). This guarantees the displayed data reflects what's actually in Salesforce.

Examples

Filter a Data Table by a Text Variable

The user types in a search box, and the Data Table updates to show matching records.

Create a Text Variable:

API Name: searchTerm
Data Type: Text
Default Value: empty

Add an Input:

Drag an Input component onto the Canvas.
Bind its value to {!searchTerm}.
Add an interaction on Change that assigns the input value to searchTerm.

Filter the Data Table:

Add a Data Table with a Query Data Source on the Account object.
Filter: Field Name, Operator Like, Value %{!searchTerm}%. The % wildcards must be supplied — Avonni passes the value through to SOQL as written.

Capture a Flow's Apex-Defined Output in a JSON Variable

A Flow returns a list of enriched Account records as an Apex-defined output. Display them in a Data Table.

Create a JSON Collection Variable:

API Name: enrichedAccounts
Data Type: JSON
Allow multiple values: checked
Build the Structure to match the Apex type's fields exactly: id (String), name (String), industry (String), revenue (Number).

Run the Flow and Map the Output:

Add a button with a Flow Builder Integration interaction.
In the Output Variables section, map the Flow's apexCollectionOutput to enrichedAccounts.

Display the Results in a Data Table:

Add a Data Table with Data Source set to Variable.
Pick enrichedAccounts.
Map columns to the Variable's structure paths: name, industry, revenue.

Build a Repeating List from a JSON Collection

A JSON Collection of project tasks rendered as cards using a Repeater.

Create the Variable:

API Name: tasks
Data Type: JSON
Allow multiple values: checked
Structure: id (String), title (String), assignee (String), dueDate (String), isComplete (Boolean).

Bind a Repeater:

Drag a Repeater onto the Canvas.
Set Data Source to Variable and pick tasks.
Inside the Repeater item template, place a Card and bind its title to {{Record.title}}, body to {{Record.assignee}} — Due {{Record.dueDate}}.

Chart a JSON Collection

Render a quarterly revenue trend from a JSON Collection returned by a Flow or Apex.

Create the Variable:

API Name: revenueByQuarter
Data Type: JSON
Allow multiple values: checked
Structure: quarter (String), revenue (Number).

Bind a Chart:

Drag a Chart component onto the Canvas.
Set Data Source to Variable and pick revenueByQuarter.
Map the X axis to quarter and the Y axis to revenue.

Troubleshooting

Problem

Cause

Fix

Variable's value is empty after a Save / Update

Variable resets after a DML operation.

Re-assign the value with an Assignment Interaction chained after the Save action.

JSON Variable's nested path returns no value ({!user.email} is empty)

The path doesn't match the structure, or the JSON object is missing that property.

Open the Structure Editor and confirm the path exists. Check field name casing. For dynamic data, inspect the source value in the Debug Panel.

Data Table fed by a JSON Collection shows no rows

The Variable is empty, or Allow multiple values is not checked.

Verify the Variable holds a non-empty array — open the Debug Panel and inspect the value. Confirm Allow multiple values is on for the Variable.

Cannot find Variable in the resource selection list

The property doesn't accept the Variable's data type.

Check the property's expected type. For example, a Text input won't show a JSON Collection Variable in its picker.

Assignment Interaction on a JSON Variable replaces everything instead of one field

JSON only supports the Equals operator, which writes the entire Variable value.

Build the full JSON object in the assignment value, use a Formula to compose it, or push the update through a Flow. See Updating a Single Field of a JSON Variable.

Variable not visible to a Flow input

The Availability is set to Output only (or not set at all).

Open the Variable, check Input under Availability Outside of this Dynamic Component.

Apex-defined Flow output doesn't map to JSON Variable

The Variable's Structure doesn't match the Apex type.

Open the Structure Editor and rebuild the structure to mirror the Apex type's field names and types. Field names are case-sensitive.

Repeater renders nothing or shows raw text instead of values

Wrong reference syntax inside the Repeater — {!variableName} is used instead of {{Record.field}}.

Inside loops, use the loop-scoped syntax {{Record.field}} to reference the current item's properties.

Key Considerations

Variables reset on DML. Plan for this when designing flows that need to persist values across saves.
JSON Variables are the link to Flows and Agentforce. Use them whenever data crosses the boundary between your component and external systems.
JSON only supports full-value assignment. Build the entire structure in your Assignment Interactions, compose it with a Formula, or rely on a Flow to return the updated object.
Field names are case-sensitive when JSON Variables receive data from Apex, Flows, or Agentforce. Match the source exactly.
Use API names you'll recognize months later. selectedRegion is clearer than var1 when you revisit the component to extend it.
Test with the Debug Panel. Paste raw JSON to validate your structure before wiring up the real data path

Last updated 1 month ago

Was this helpful?