> For the complete documentation index, see [llms.txt](https://docs.valorx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valorx.com/valorx-wave/surf-the-wave/publish-the-grid/salesforce-components.md). # Salesforce Components You can add a **Valorx Grid** to Salesforce components and Screen Flows so users can view and work with Salesforce data without leaving their current Salesforce experience. You can use a Valorx Grid in: * **Aura Components** for custom Salesforce components. * **Screen Flows** for guided Salesforce processes. * **Lightning Web Components (LWC)** when you need more control over how the Grid is configured and used. You can add either a **Valorx Grid** or a **Valorx Related Grid**, depending on the data you want to display. #### Which option should I use?

If you want to...	Use
Add a Grid to a custom Salesforce component	Aura Component
Add a Grid to a guided Salesforce process	Screen Flow
Build a custom Salesforce component and control the Grid through code	Lightning Web Component (LWC)

> **Note:** The LWC option requires Salesforce development knowledge. If you are using a Screen Flow, you can add a Valorx Grid without creating an LWC. #### Before you begin Before you start, make sure you have: * A Valorx Grid that you want to add to Salesforce. * The **Grid ID** for the Grid. * The Salesforce access required to add or configure the component or Flow. Don't know where to find it? See [Get Grid ID](#get-grid-id). *** ## Use Valorx Grid in an Aura Component You can embed a **Valorx Grid** or **Valorx Related Grid** in an Aura Component. Use this option when your Salesforce team is building a custom Aura Component and wants users to work with Grid data directly from that component. Before you begin, make sure you: * Are familiar with **Lightning Components (Aura Components)**. * Have already created the Valorx Grid you want to use. #### What is the difference between the two Grid types? **Valorx Grid**\ Displays records from the object selected for the Grid. For example, you can display a Grid containing Account records. **Valorx Related Grid**\ Displays records related to the record the user is currently viewing. For example, you can display Contacts related to the current Account. This guide demonstrates how to configure both **Valorx Grid** and **Valorx Related Grid** within a Lightning Component. {% stepper %} {% step %} #### Create the Lightning Component 1. In Salesforce, click **Setup** and open the **Developer Console**. 2. In the Developer Console, click **File** > **New** > **Lightning Component**. 3. Enter a component name, such as `MyGridComponent`. 4. Select the component availability based on your requirements. 5. Click **Submit**. **If you are using a Valorx Related Grid** A Related Grid needs the ID of the parent record so it knows which records to display. Define the **Parent Record ID** as a parameter by adding the following code to your component: {% code overflow="wrap" expandable="true" %} ```json ``` {% endcode %}

{% endstep %} {% step %} #### Add the Valorx Grid and Related Grid Use `lightning:tabset` to display the Valorx Grid and Related Grid. The following example shows both types of Grid: {% code overflow="wrap" fullWidth="false" expandable="true" %} ```json

``` {% endcode %} #### Configure the Grid

Parameter	What it does
Grid ID	Identifies the Grid you want to display. Use the format `ObjectName::GridId`.
height	Sets the height of the Grid.
canChangeGrid	Allows users to switch between Grids for the same object when enabled.
relationshipName	Specifies the Lookup Relation Name for a Related Grid.
recordId	Specifies the Parent Record ID for a Related Grid.

For information about finding the Grid ID, see [Get Grid ID](#get-grid-id). > **Important:** Save the component after configuring the parameters so that your changes take effect.

{% endstep %} {% step %} #### Add the Component to a Record Page After creating and configuring the component, add it to the Salesforce Record Page. 1. Navigate to the **Account Record Page** and click **Edit Page**. 2. In the **Custom Components** section, find **MyGridComponent**. 3. Drag **MyGridComponent** to the section where you want the Grid to appear. 4. Click **Save**. 5. Return to the Record Page and verify that the Grid is displayed.

{% endstep %} {% endstepper %} Your Valorx Grid is now available in the Aura Component. *** ## Use Valorx Grid in a Screen Flow {% hint style="info" %} Available in Valorx Wave v10 and later. {% endhint %} You can add a **Valorx Grid** or **Valorx Related Grid** to a Salesforce **Screen Flow**. This allows users to work with Grid data as part of a guided Salesforce process. {% stepper %} {% step %} #### Create a New Flow * Click **Setup** and search for **Flow** in the **Quick Find** box. * Click **New Flow** → Select **Start from Scratch** → Select **Screen Flow** → Click **Create**.

{% endstep %} {% step %} #### Add a Screen * Drag a **Screen** element from the **Element** panel to the Flow canvas. You can also click the **+** button and select **Screen**. * Enter a **Screen Component Label**, such as `Valorx Grid`.

{% endstep %} {% step %} #### Add a Valorx Grid 1. In the left panel, scroll to **Components**. 2. Find the **Custom** section. 3. Drag the **Valorx Grid component** onto the Screen. 4. Configure the following properties:

Property	What it does
API Name	Specifies the component's API name.
Grid ID	Identifies the Grid you want to display. Use the format `ObjectName::GridId`.
Height	Sets the height of the Grid.
Allow Changing Grids	Allows users to switch between Grids for the same object when enabled.

For information about finding the Grid ID, see [Get Grid ID](#get-grid-id).

{% endstep %} {% step %} #### Add a Valorx Related Grid You can also add a Related Grid to the same Screen. 1. Follow the same steps to add the **Related Grid component** below the Valorx Grid. 2. Configure the following properties:

Property	What it does
Grid ID	Identifies the Related Grid you want to display.
Height	Sets the height of the Related Grid.
Allow Changing Grids	Allows users to switch between Grids for the same object when enabled.
Relationship Name	Specifies the Lookup Relation Name used to connect the related records to the parent record.
Record ID	Specifies the Parent Record ID.

For information about finding the Grid ID, see [Get Grid ID](#get-grid-id).

Embed Valorx Related Grid in Screen Flow

{% endstep %} {% step %} #### Save and Activate the Flow * Click **Done** → Click **Save** and provide a **Flow Label**. * Click **Activate** to enable the Flow.

{% endstep %} {% endstepper %} Your Screen Flow is now ready to use the Valorx Grid. ### Add an Input Variable in Flow Use an input variable when you need to pass a record ID into a Salesforce Flow. To add an **Input Variable** in Flow: 1. In Flow Builder, click **+ New Resource**. 2. Set **Resource Type** to **Variable**. 3. Enter `recordId` as the **API Name**. 4. Set **Data Type** to **Text**. 5. Select **Available for Input**. 6. Click **Done**.

*** ## Use Valorx Grid in a Lightning Web Component (LWC) You can add a **Valorx Grid** or **Valorx Related Grid** to your own Lightning Web Component (LWC) and place it on a Salesforce App Page, Record Page, or Home Page. This guide shows you how to: * Add a Valorx Grid to your LWC. * Configure the Grid. * Deploy the component to Salesforce. * Optionally pass records to the Grid, display related records, or read records selected by users. {% hint style="info" %} **Availability:** LWC support is available in Valorx Wave v22 and later. {% endhint %} ### Before you begin Make sure the following requirements are met in your Salesforce org:

Requirement	Details
Valorx Wave package	The Valorx Wave managed package must be installed.
User permission	Assign Vx Grid Runtime User to users who need to use the Grid. If they also build Grids, assign Vx Grid Design Studio User.
Experience Cloud users	Assign Valorx Grid Runtime User for Experience Cloud to users accessing the Grid through Experience Cloud.
Salesforce API version	Your LWC must use Salesforce API version 55.0 or later.

The Grid checks the user's permissions before it loads. If the user does not have the required permission, an **Insufficient Permission** message is displayed instead of the Grid. {% hint style="info" %} You also need the **Grid ID** of the Grid you want to display. Keep the Grid ID ready. You will add it to your LWC in the next step.\ For more information, see [Get Grid ID](#get-grid-id). {% endhint %} {% stepper %} {% step %} #### Create the wrapper component Create a standard Lightning Web Component in your Salesforce project. For this example, we'll call the component `myGridWrapper`. Your component contains three files: ``` myGridWrapper/ ├── myGridWrapper.js ├── myGridWrapper.html └── myGridWrapper.js-meta.xml ```

You will configure each file in the following steps. {% endstep %} {% step %} #### Add the Valorx Grid to the HTML file Open `myGridWrapper.html` and add the following code: {% code title="myGridWrapper.html" overflow="wrap" %} ```html ``` {% endcode %} This adds the packaged Valorx Grid to your LWC. The values in `{ }` connect the Grid attributes to properties in your JavaScript file. For example: `grid-id={gridId}` connects the Grid's `grid-id` attribute to the `gridId` property in your JavaScript file.

{% endstep %} {% step %} #### Configure the Grid in the JavaScript File This file defines the values used by the Grid and sets up the listener that captures the user's Grid selection. Open `myGridWrapper.js` and add the following code: {% code title="myGridWrapper.js" overflow="wrap" %} ```js import { LightningElement, api } from 'lwc'; export default class MyGridWrapper extends LightningElement { @api recordId; // supplied by a record page, or set it yourself gridId = 'Account::a0X5g000004ABCDEAO'; //update this to your Grid ID height = 700; // px; minimum 600 canChangeGrid = false; relationshipName; // related-list mode only externalVariables = 'Status=Open,Closed;Priority=High'; inputRecords; // JSON string gridConfig; // JSON string, forwarded to the grid app selectedRecords = []; connectedCallback() { this.template.addEventListener( 'lightning__flowattributechange', this.handleGridChange ); } handleGridChange = (event) => { const { attributeName, value } = event.detail; if (attributeName === 'outputRecords' && value) { const parsed = JSON.parse(value); // { records: [...], objectId: 'Account' } this.selectedRecords = parsed.records; } }; } ``` {% endcode %} Replace the example `gridId` with the Grid ID you want to display. You can then customize the other properties depending on what you want your Grid to do.

*** ### Grid properties

HTML attribute	JS property	Type	Description
`grid-id`	`gridId`	String	Required. `ObjectAPIName::ViewId`.
`height`	`height`	Integer	Grid height in pixels. Minimum 600. Omit it and the grid falls back to `85vh`.
`can-change-grid`	`canChangeGrid`	Boolean	Shows or hides the in-grid view switcher, letting users move between views they have access to.
`record-id`	`recordId`	String	Record context for the grid. Also affects page styling — see Important Behavior.
`relationship-name`	`relationshipName`	String	API name of the lookup field on the child object, for example `AccountId`. Switches the grid into related-list mode.
`external-variables`	`externalVariables`	String	Dynamic filter inputs in the form `Field=value1,value2;Field2=value3`.
`input-records`	`inputRecords`	String	JSON payload of records to load into the grid. See Display related records.
`grid-config`	`gridConfig`	String	JSON configuration passed through to the grid application. See Dynamic Grid.
`output-records`	`outputRecords`	String	Read-only from the consumer’s point of view. See Read Records Selected by the User.

*** {% endstep %} {% step %} #### Configure The Component Metadata Open `myGridWrapper.js-meta.xml`. and add the following configuration: {% code title="myGridWrapper.js-meta.xml" overflow="wrap" %} ```xml 62.0 true My Grid Wrapper lightning__AppPage lightning__RecordPage lightning__HomePage ``` {% endcode %}

Here's what each setting does:

Setting	Description
`apiVersion`	Specifies the Salesforce API version used by the component. The example uses 62.0, which meets the minimum requirement of 55.0.
`isExposed`	Makes the component available in Lightning App Builder.
`targets`	Specifies where you can place the component.

This example allows you to add the component to: * App Pages * Record Pages * Home Pages {% endstep %} {% step %} #### Deploy and Add The Component Deploy the component to your Salesforce org. For example, using Salesforce CLI: ``` sf project deploy start --source-dir force-app/main/default/lwc/myGridWrapper ```

Deploy the component using Lightning Studio

After the deployment is complete: 1. Open **Lightning App Builder**. 2. Open the App Page, Record Page, or Home Page where you want to add the Grid. 3. Find your **My Grid Wrapper** component. 4. Drag the component onto the page. 5. Save and activate the page.

Your Valorx Grid is now available on the Salesforce page. {% endstep %} {% endstepper %} *** ## Optional Configurations The following configurations are only needed for specific use cases. If you only need to display a Grid, you can skip this section. ### Pass Records Into The Grid Use `inputRecords` when your LWC needs to provide a specific list of records to the Grid. For example: ```json this.inputRecords = JSON.stringify({ objectId: 'Account', records: [ { Id: '0015g00000XyZ12AAB' }, { Id: '0015g00000XyZ13AAB' } ] }); ``` The payload must contain: * `objectId`: API name of the Salesforce object. * `records`: array of records. The Grid retrieves the fields required by the configured Grid view and processes the records in batches of 1,000. You can provide up to **10,000 records**. If the JSON is invalid or either required property is missing, the Grid displays a validation error. > **Important:** `inputRecords` is read when the Grid first loads. Changing its value afterward does not automatically update the Grid. *** ### Display Related Records Use related-list mode when you want the Grid to display records related to another Salesforce record. For example, you can display Contacts related to an Account. You need: * `recordId`: the ID of the parent record. * `relationshipName`: the lookup field that connects the child record to the parent. Example: ```json ``` In this example: * `grid-id` identifies the Contact Grid. * `record-id` identifies the current Account. * `relationship-name="AccountId"` tells the Grid how the Contact is related to the Account. The `relationshipName` value must be the API name of the lookup field on the child object. *** ### Read Records Selected by the User Use `outputRecords` if your LWC needs to know which records the user selects in the Grid. When a user selects records, the Grid returns the selected records in the following format: ```json { "records": [ { "Id": "0015g00000XyZ12AAB", "Name": "Acme Corp" } ], "objectId": "Account" } ``` #### Listen for selection changes Add the following listener to your JavaScript file: ```js connectedCallback() { this.template.addEventListener( 'lightning__flowattributechange', this.handleGridChange ); } ``` Then add the event handler: ```js handleGridChange = (event) => { const { attributeName, value } = event.detail; if (attributeName === 'outputRecords' && value) { const parsed = JSON.parse(value); this.selectedRecords = parsed.records; } }; ``` You can then use `this.selectedRecords` in your LWC. > **Note:** Use `addEventListener()` to listen for `lightning__flowattributechange`. The standard LWC `on...` template syntax does not work with this event name. #### Read the current selection directly You can also read the current selection directly from the Grid: ```json const grid = this.template.querySelector('valorxwave-valorx-grid'); const output = JSON.parse(grid.outputRecords); ``` *** ## Important Behavior Keep the following points in mind when working with the Grid. #### Most Grid properties are applied when the Grid loads The following properties are read when the Grid first loads: * `gridId` * `height` * `canChangeGrid` * `recordId` * `relationshipName` * `externalVariables` * `inputRecords` If you change these values after the Grid has loaded, the Grid does not automatically update. To apply the new value, remove and recreate the Grid component. For example: ```js ``` Then recreate the Grid after changing the value: ```js switchGrid(newGridId) { this.showGrid = false; this.gridId = newGridId; Promise.resolve().then(() => { this.showGrid = true; }); } ``` `gridConfig` is the exception. Changes to `gridConfig` can be applied after the Grid has loaded. #### An empty `recordId` hides the Salesforce page header If `recordId` is empty, the Grid hides the standard Salesforce page header so it can use the available page height. This is expected behavior. If you want the Salesforce page header to remain visible, provide a `recordId`. #### Use only one Grid per page Only one Valorx Grid should be embedded on a page. Using multiple Grids on the same page is not supported and may cause the Grids to interfere with each other. #### Keep the Grid at least 600 px high Keep the Grid at least **600 px** high. The Grid's toolbar and pagination controls need enough vertical space to display correctly. *** ## Troubleshooting

Problem	What to check
Insufficient Permission message	Make sure the user has Vx Grid Runtime User or the appropriate Experience Cloud permission.
Grid area is blank	Check that the Grid ID contains both the object name and View ID, separated by `::`.
Validation error	If you are using `inputRecords`, make sure it contains valid JSON with both `objectId` and `records`.
Changing a property does not update the Grid	Most properties are applied when the Grid loads. Recreate the Grid to apply the new value.
Salesforce page header disappears	This happens when `recordId` is empty. Provide a `recordId` if you want the header to remain visible.
Selected records are not returned	Make sure `lightning__flowattributechange` is registered with `addEventListener()` on `this.template`.

*** ## Get Grid ID You can get the Grid ID from either the **Wave Dashboard** or the **Surf the Wave** tab. #### Option 1: From the Wave Dashboard 1. Open the **Wave Dashboard**. 2. Find the grid for which you want to get the Grid ID. 3. Click the **More options (⋮)** button for the grid. 4. Select **Publish**. 5. In the **Grid Publish Details** window, look at the **top-right corner** to find the **Grid ID**. 6. Click the **Copy** icon next to the Grid ID to copy it.

#### Option 2: From the Surf the Wave Tab 1. Open the **Surf the Wave** tab. 2. Open the grid for which you want to get the Grid ID. 3. At the top right, click **How to Publish** or **Published** button. 4. The **Grid Publish Details** window opens. 5. In the **top-right corner**, find the **Grid ID**. 6. Click the **Copy** icon next to the Grid ID to copy it.

> **Tip:** You can use either method to get the same Grid ID. If you already have the grid open in the **Surf the Wave** tab, using **How to publish** or **Published** is usually the quickest way to find it. ***