# 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](/dynamic-components/component-builder/resources/constant.md) (which never changes) or a [Formula](/dynamic-components/component-builder/resources/formula.md) (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 1. Click the Resources button to open the Resources panel. 2. Click New Resource, then choose Variable. 3. API Name: `selectedRegion` 4. Data Type: Text 5. Default Value: `North America` 6. 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 1. Drag a Combobox onto the Canvas. 2. In the Properties Panel, set Options to a Manual list with `North America`, `EMEA`, `APAC`. 3. Set Value to `{!selectedRegion}` so the Combobox reads from the Variable. ### Wire the Combobox to update the Variable 1. With the Combobox selected, open the Interactions tab. 2. Add an interaction on the Change trigger. 3. Action: Assignment. 4. Target: `selectedRegion` Variable. 5. Operator: Equals. 6. Value: `{!Component.Value}` — the new Combobox value. ### Filter a Data Table by the Variable 1. Drag a Data Table onto the Canvas. 2. Configure its Data Source as a Query on the Account object. 3. Add a filter: Field `BillingCountry`, Operator `Equals`, Value `{!selectedRegion}`. 4. 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: 1. Open the Resources panel. 2. Click New Resource, then select Variable. 3. Fill in the configuration fields described below. 4. 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) — `"cedric@avonni.app"` * `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 1. Open the property where you want the Variable's value. 2. Click the resource selection icon next to the field. 3. 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. 1. Drag a data-aware component onto the Canvas (Data Table, List, Kanban, Map, Repeater, Chart, etc.). 2. In the Properties Panel, set Data Source to Variable. 3. Pick your JSON Collection Variable from the list. 4. 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. 1. Select the component that triggers the assignment. 2. Open the Interactions tab. 3. Add an interaction on the relevant trigger. 4. Choose Assignment as the action. 5. Pick the target Variable, choose an operator, and supply the value. Operators by data type:
Data TypeOperators
TextEquals, Add (concatenate), Replace, Replace All, Replace by Regex
NumberEquals, Add, Subtract
BooleanEquals, Toggle
Date / Date/TimeEquals, Add (days), Subtract (days)
JSONEquals (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: 1. **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. 2. **Use a Formula Resource to compose the new structure** and reference the Formula in the assignment value. Cleaner when the object has many fields. 3. **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. 1. Configure a Flow Builder Integration interaction on the component. 2. After the Flow runs, map its output variables to your Dynamic Component Variables in the Output Variables section. 3. 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. 1. Create a JSON Variable `recommendedLeads` with Allow multiple values checked. 2. Build the Structure: `id` (String), `name` (String), `score` (Number), `reason` (String). 3. Set Availability to Input. 4. In the Agentforce action configuration, map the agent's response fields to the corresponding paths in `recommendedLeads`. 5. 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 *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.avonnicomponents.com/dynamic-components/component-builder/resources/variable.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.