UI Builder Essentials: Dynamically Binding the List Component With a Data Visualization

[MGOPW]

UI Builder Essentials Part 3

Table of Contents

• Create a Page
• Add a Two-Column Layout
• Add a Pie Chart to the Left Column
• Add a List to the Right Column
• Create a Client State Parameter
• Configure the Pie Chart to Update the Parameter
• Bind the List Filter to the Parameter

Article Directory

Part 1 - Six Fundamental Features You Need to Know Part 2 - Navigating UI Builder Part 3 - Dynamically bind List with Data Visualization Part 4 - Implementing Popovers Part 5 - Updating Component's Data with a Button

Overview

In this tutorial, you will create a dynamically filtered list that gets it's content from a Data Visualization component. 

Family Release: Xanadu

UI Builder Release: 26.2.59

Roles Required: admin

Authored by: @michaelburney 

📌

Quick Tip

If you haven't gone through the steps to create the Customer Support Workspace, check out our article on how to make a workspace from scratch!

Step 1: Open UI Builder

1. In your ServiceNow instance, use the Unified Navigator to go to Now Experience Framework > UI Builder.

2. When UI Builder opens, you should see the UI Builder Home screen.

3. Select the Experiences Tab at the top of the screen.

4. Open the Customer Support Workspace.

Lets create a new page in the Experience Editor.

Step 2: Create a Page

1. In the Experience Editor, find Pages and variants.

2. Click the + (plus) icon next to it.

3. Select Create from scratch instead.

4. Enter the page name "Home Base". The URL path auto-populates.

5. Click Continue, then Looks good on the next screen.

6. Leave the variant name as Default or rename it.

7. Select Build Responsive

8. Click Create.

You should now have an empty Page, that's ready to be built upon, so let's add a layout!

Step 3: Add a Two-Column Layout

1. Under Body inside the Component Tree, click the + Add content button.

2. Search for Two Columns (or select it from the Layouts category).

3. Click to add the Two Columns layout to the page.

Now lets create a pie chart with "true" vs "false" slices.

Step 4: Add a Pie Chart to the Left Column

1. In the left column (Column 1), click the + (plus icon) to add a component.

2. Search for the Data Visualization component and Select it.

3. In the Component Configuration panel, under the Configure tab, expand the Data Sources category, and select Add data source.

4. Search for "Incident", and under the Tables category select Incident and Add this source at the bottom.

5. Under Column 1, select the Data Visualization component we just added. The Component Configuration panel should open to the right.

6. Inside the Configure tab, find the  Data visualization type field and select Pie.

7. Scroll down in the Component Configuration panel, find the Group by category and expand it. Select Active. 

You should now have a pie chart displaying on the page, Lets add a list of records now.

Step 5: Add a List to the Right Column

1. Back on the left in the Component Tree. In the right column (Column 2), click + Add content to add a component.

2. Search for "List".

3. Select the List component.

4. Select the List 1 component from the Component Tree, beneath Column 2.

5. Navigate to the List component's Component Configuration panel on the right, within the Configure tab, and fill in the Table property by selecting Incident.

We now have a pie chart on the left, and a list of records on the right, next we'll use a client state parameter to store the filter query coming from our pie chart interactions.

Step 6: Create a Client State Parameter

1. At the bottom-left of the Editor, under Data and scripts, selectClient State Parameters.

2. Click the + (plus) icon to create a new parameter and fill in the fields as follows: 

Name: queryParam

Type: String

Initial Value: (leave blank)

3. Close the client state parameters window and hit the Save button in the top right.

Now lets bind the pie chart click events to our newly created client state parameter.

Step 7: Configure the Pie Chart to Update the Parameter

1. Back on the left in the Component Tree, In the left column (Column 1), click on the Pie 1 component. 

2. In the Component Configuration panel to the right, select the Events tab.

3. Select Add event mapping.

4. Choose the Visualization Clicked event, then click Continue.

5. Select the Update Client State Parameter event handler, then click Continue.

6. Under Client State Parameter Name, Select the client state parameter you created (queryParam).

7. Hover over the Value to use after triggering event field, in the top right corner of the box, until you see the Bind Data (stacked circles) icon then Click it.

8. In the Data Binding modal, select the Event payload Data type in the left column. 

9. Scroll down until you find "params.query", then click the small up arrow next to it or drag-and-drop the pill into the top of the binding area.

📌

Quick Tip

Double Click the Pill at the top of the binding area and ensure the bindings value reads @payload.params.query and not something like @payload."params.query". If you notice the quotations, double click on the pill at the top and update it to read @payload.params.query.

10. Click Apply, then Add.

Next, we configure the List to use the client state parameter in its filter.

Step 8: Bind the List Filter to the Parameter

1. Select the List 1 component, under Column 2, and go to the Component Configuration panel on the right. 

2. Go to the Configure tab, expand the Data category if it's collapsed.

3. Hover over Edit Fixed Filter, then click the Data Binding icon (stacked circles) that appears.

4. In the data binding window, under the Data Types tab, select Client States.

5. In the Pill view, you should see the client parameter queryParam.

6. Use the up arrow or drag-and-drop the parameter pill into the top area.

7. Click Apply to confirm the binding. Then hit the Save button on the top right corner.

Note:

Depending on the UI Builder release, the filter for the list component will have a condition of Active = True already selected. To ensure our dynamic filtering works as intended, check if the Edit Filter property under the Default display category is empty.

Here's how you do this:

1. Select the List 1 component in the Component Tree, under Column 2.

2. Navigate to the Component Configuration panel, and select the Configure tab. 

3. Expand the Default display category, select the Edit Filter button.

4. If you see a filter applied here, remove it then click Apply.

Step 9: Save and Preview

1. Click Save in the upper-right corner of UI Builder.

2. Click Preview (or open the experience in a new tab).

In preview mode:

• Click the various slices in the pie chart (true/false).
• Observe that the List component updates to display incidents based on the selected slice (filtered by true or false).

📌

Troubleshooting

If the list does not filter correctly when you click a pie slice, re-check your event mappings to ensure that:

• The pie chart Visualization Clicked event updates the correct Client State Parameter.
• The Value in the event mapping is correctly bound to @payload.params.query.
• The List component’s Fixed Filter is correctly bound to the same Client State Parameter.
• Ensure you Save after each change and refresh your preview to load the new configuration.

Conclusion

Congratulations! 🎉 You've now built an interactive data visualization enhanced with a dynamic list, allowing users to explore insights in real time. This is a significant step toward creating responsive, user-centric interfaces.

If you found this guide helpful, consider sharing it with peers or teams looking to elevate their UI Builder skills with dynamic visualizations.

Keep an eye out for future tutorials where we’ll dive deeper into crafting immersive, data-driven experiences. Until then—happy designing, and stay curious!

Check out the Next Experience Center of Excellence for more resources

[RaviAmbati]

Very well articulated. Two of the most popular components in UI Builder.

[gjz]

Just in time, this was what I was looking for!  I got it to work, but one clarification, please.

In Step 5: Add a list to the right column and within that step, it's step 5 says "5. Navigate to the Data Visualization's Component Configuration panel on the right, within the Configure tab, and fill in the Table property by selecting Incident."  

Navigate to the Data Visualization like stated or to the list like the screen shot?

[RaviAmbati]

@gjz you are right. I think It should be List component configuration. 

[MGOPW]

@gjz Thank you! I totally missed that, my bad. Consider it fixed 🙂 

[udaykumar98]

Thanks

[IosifH]

Thank youuuu!

[HAMDI Oussema]

This was what I was looking for!
Thank you