For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.


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.

1

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:

Create the Lightning Component
2

Use lightning:tabset to display the Valorx Grid and Related Grid.

The following example shows both types of Grid:

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.

Important: Save the component after configuring the parameters so that your changes take effect.

Add Valorx Grid and Related Grid
3

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.

Deploy the Component on a Record Page

Your Valorx Grid is now available in the Aura Component.


Use Valorx Grid in a Screen Flow

Available in Valorx Wave v10 and later.

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.

1

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.

Create a new Flow
2

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.

Add a Screen Flow
3

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.

Embed Valorx Grid in the Screen Flow
4

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.

Embed Valorx Related Grid in Screen Flow
5

Save and Activate the Flow

  • Click Done → Click Save and provide a Flow Label.

  • Click Activate to enable the Flow.

Save and Activate the Flow

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.

Add an Input Variable in Flow

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.

Availability: LWC support is available in Valorx Wave v22 and later.

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.

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.

1

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:

Create the wrapper component

You will configure each file in the following steps.

2

Add the Valorx Grid to the HTML file

Open myGridWrapper.html and add the following code:

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.

Add the Valorx Grid to the HTML file
3

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:

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.

Configure the Grid in the JavaScript File

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.


4

Configure The Component Metadata

Open myGridWrapper.js-meta.xml. and add the following configuration:

Configure The Component Metadata

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

5

Deploy and Add The Component

Deploy the component to your Salesforce org.

For example, using Salesforce CLI:

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.

Save and Activate the component

Your Valorx Grid is now available on the Salesforce page.


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:

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.


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:

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:

Listen for selection changes

Add the following listener to your JavaScript file:

Then add the event handler:

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:


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:

Then recreate the Grid after changing the value:

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.

Grid ID Wave Dashboard

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.

Grid ID Surf The Wave

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.


Last updated

Was this helpful?