The CreatorCon Call for Content is officially open! Get started here.

MGOPW
ServiceNow Employee
ServiceNow Employee

Checklist - Basic configuration

Articles Hub

Want to see all of our other articles and blogs related to UI Builder and Workspaces?

You can copy the link above and share it!

We Value Your Feedback!

Have any suggestions or topics you'd like to see in the future? Let us know!


Overview

In this tutorial, you will configure your Workspace to include a Checklist component. The Checklist component provides some default values out of the box so that the component can be set up to show data without much configuration. By the end you will have a working checklist that renders immediate updates as items are checked and provides a solid foundation for advanced configurations.
This guide assumes you are meeting these environment requirements:

Family Release: Xanadu
UI Builder Release: 26.2.59
Roles Required: admin

You will:

  • Create a Workspace Experience using UI Builder.
  • Add a Checklist component.
  • Configure its parameters.

Step 1. Getting Started


  1. Log in to your ServiceNow instance.
  2. Navigate to Now Experience Framework > UI Builder in the filter navigator to open the UI Builder interface.
MichaelB6948013_0-1759611276506.png

3. Click Create (in the upper right corner) > Experience
MichaelB6948013_1-1759611276507.png

4. Fill in the fields as such:
    Name: Checklist Configurations
    App Shell UI: Workspace App Shell
    URL Path: checklist-configurations
    Landing Path: home
    Roles: canvas_user
MichaelB6948013_2-1759611276508.png

5. Click Create
6. On the following pop up, click Open experience
You now have a Workspace Experience shell!

Step 2. Adding Page


  1. Select the plus button next to Pages and Variants
MichaelB6948013_3-1759611276509.png

  1. Select Create from scratch instead
MichaelB6948013_4-1759611276509.png

  1. Update Name to "My Checklist"
  2. Click Continue
MichaelB6948013_5-1759611276510.png

  1. Select Looks good
  2. Leave variant name as Default then select Continue
  3. Select Build responsive
  4. Select Create
MichaelB6948013_6-1759611276510.png

You now have a Next Experience page that's ready to undergo development!

Step 3. Adding the Checklist Component


  1. In the content tree, underneath the Body, select Add content > Components > Content > Checklist > Add
MichaelB6948013_7-1759611276511.png

If your version of UI Builder displays a Select a preset pop up immediately after adding the Checklist component to the page, select Cancel to close it.
MichaelB6948013_8-1759611276511.png

Step 4. Create Checklist Data


To populate the checklist initially we will carry out the following steps:
MichaelB6948013_9-1759611276512.png

  1. Under Data and scripts > select Client state parameters
  2. Create the parameter as such:
  • Name: checklistData
  • Type: JSON
  1. Initial value: select Edit, then change mode to JSON.
MichaelB6948013_10-1759611288945.png

  1. Copy and paste JSON from below:
[
  {
    "itemId": "checkbox_1",
    "label": "This is item 1",
    "checked": false,
    "order": 0
  },
  {
    "itemId": "checkbox_2",
    "label": "This is item 2",
    "checked": false,
    "order": 10
  }
]
The result should resemble screenshot below:
MichaelB6948013_11-1759611288945.png

5. Select Apply
6. Then select Apply again to close the Client state parameters pop up.
NOTE: Each checklist item is represented by an object containing at minimum: itemId, label, checked, and optionally order.

Step 5. Bind Checklist Data to Component


For our checklist to apply to our component, the parameter we created must bind to the component itself. To do so:
  1. On the Component configuration panel navigate to: Configure > Data and display > hover over Checkbox items until you see the stacked circles icon (Bind data) > select the icon
MichaelB6948013_12-1759611288946.png

2. Under the Data types tab > Client states > select the checklistData pill
3. Click the small arrow to the right of the pill to move it to the top
4. Select Apply
MichaelB6948013_13-1759611288946.png

NOTE: This data binding ensures your checklist updates dynamically as checklistData changes.

Step 6. Capture Users Interaction


  1. Create a client script: go to Data and scripts > Client scripts > select the small + to the right
Update the Edit client script pop up as follows:
Script Name: Item Checked
Script:
/**
 * @param {params} params
 * @param {api} params.api
 * @param {any} params.event
 * @param {any} params.imports
 * @param {ApiHelpers} params.helpers
 */
function handler({ api, event, helpers, imports }) {
  // Make a copy of the existing checklist array so we don’t mutate state directly
  const clData = [...api.state.checklistData];

  // Find the checklist item matching the clicked item and update 'checked'
  clData.find((item, i) => {
    if (item.itemId === event.payload.itemId) {
      clData[i] = { ...clData[i], checked: event.payload.checked };
      return true;
    }
    return false;
  });

  // Write the updated array back into state to trigger UI updates
  api.setState("checklistData", clData);

  // Optional: Persist the updated status to backend here
}
2. Select Apply

Save and Test!


  1. Select the Save button in the upper right corner of the screen.
  2. Select Preview to open the preview panel.
MichaelB6948013_14-1759611288947.png

  1. You should now see the two checklist items that were created and be able to select one or both.
MichaelB6948013_15-1759611288947.png

Troubleshooting


If any functionality is missing after configuration, double-check your UI Builder version as well as your family release. Matching the environment in this article reduces hiccups.
Cache can also cause issues. Be sure to reset the UI Builder cache as well as your browser cache from time to time to ensure your browser is working from a clean slate.

Conclusion

Congratulations! 🎉 You now have a fully functional and interactive Checklist component within your Workspace. Stay tuned for Part 2 where we cover advanced configurations for the Checklist component!

 

If you found this guide helpful, consider sharing it with peers or teams looking to elevate their UI Builder skills with dynamic pages. If you like this type of content, please mark the article "Helpful", and leave us your topic ideas in the comments.

 

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