--- sourceDocument: Zurich Build or modify applications sourceDocumentLink: https://www.servicenow.com/docs/r/zurich/application-development Release : - zurich ft:locale : - en-US ft:publication_title : - Zurich Build or modify applications ft:clusterId : - cadev bundleId : - cadev workflow : - Development, Data, and Analytics --- # Manage actions in UI Builder pages # Manage actions in UI Builder pages {#ariaid-title1} * Release version: Zurich * * Updated July 31, 2025 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 8 minutes to read Summarize ![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) Summarized using AI This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete. ## Summary of Manage Actions in UI Builder Pages This guide provides instructions on how to manage actions within UI Builder pages by utilizing events to enhance user interactions. Events are triggered by user actions or occurrences on a page, and UI actions dictate the responses to these events, enabling the creation of interactive interfaces. Show full answer Show less ## Key Features * **Event Types:** Includes user interactions such as button clicks, data fetching, and selection changes. * **Event Handlers:** Actions configured to respond to events, allowing customization of component behavior and page responses. * **Event Mapping:** The process of linking events to specific actions, enhancing the functionality of UI components. * **Client Scripts:** Scripts that execute actions based on events for further customization. ## Key Outcomes By effectively managing actions through event handlers and mappings, ServiceNow customers can: * Create dynamic pages that respond intuitively to user input, enhancing user experience. * Configure alerts and notifications to keep users informed of important events. * Bind data resources to actions, facilitating real-time updates and interactions. * Utilize declarative actions for streamlined workflows, enhancing productivity. Learn how to work with events so that you can add actions to components, pages, data resources, and declarative actions in UI Builder. ## Actions in UI Builder {#work-events__section_qk3_tz4_xyb} UI actions tell UI Builder what to do when an [event](https://www.servicenow.com/docs/2arqazAs26lelmRHkX_Vdw#gloss-event-ui-builder "Action a user takes (such as selecting a button) or an occurrence that happens on a page. Most UI Builder components, pages, and data resources have default-associated events. Use event handlers with the events to add additional actions to pages.") is triggered. An event is an action a user takes or occurrence that happens on a [page](https://www.servicenow.com/docs/2arqazAs26lelmRHkX_Vdw#gloss-page-ui-builder "Collection of column layouts, columns, and components. Create or customize multiple UI Builder pages for workspace and portal experiences."). Use UI actions to create interactive, user-friendly interfaces that help your users complete tasks. Each [component](https://www.servicenow.com/docs/2arqazAs26lelmRHkX_Vdw#gloss-component-ui-builder "Components are used in the UI Builder to build pages. Components have an interface that an end user can view and interact with. Components can talk to each other through events and properties. Commonly used components include Heading, Image, List, Form, and Button.") has its own events associated with it. Events include: * User clicks a data visualization * Page successfully fetches data * User selects a radio button * Page loads {#work-events__ul_uqx_bq4_xyb} ## Events in UI Builder {#work-events__section_m5n_nmy_24b} Use an event to add actions to your components, pages, and data resources. * A component event is an action that you set up for a component. You set up an event handler to configure that component action. For example, you can add a button component to your UI Builder page. Then, you can add an event handler to apply an action for that button, such as going to a web page. * Page events perform actions for the entire page. You can configure the following page events: * Page event mappings. Add, remove, or clear alert notifications on your page. * Variant event mappings. Add, remove, or clear alert notifications on your page variant. * Dispatched events. Create dispatched events for your page to create relayed event mappings that model events after a parent event handler. Select a target parent event handler to model the payload fields after it. * Handled events. A handled event is an event that is exposed and available for use by other users. After you create a handled event, it is available under Page event mappings for other users to use. You can also set up payload fields that you create manually or choose a template for your handled event, such as an open or close a modal dialog. {#work-events__ul_nsx_b4y_24b} * Data resources events map data resources to notify information about when data is fetched. * Events for a page or component do nothing until the event is mapped to one or more event handlers. {#work-events__ul_dr1_3ny_24b} ## Event mapping in UI Builder {#work-events__section_ay2_4my_24b} Map actions to events such as clicking a button or filling in a field. An event mapping is the process that enables you to map an event's payload or contextual values to the object or handler that acts on that event. For more information about event mapping, see [Define map events](https://www.servicenow.com/docs/L481ot9Gs_fiR0O8y_KViw "An event mapping in UI Builder is the process that enables you to map an event's payload or contextual values to the object or handler that acts on that event. The four event types are: component, page, data resource, and declarative action."). ## Event handlers in UI Builder {#work-events__section_fmg_ffb_snb} An event handler is an action performed when an event occurs. By mapping an event handler to an event, you are specifying which action or actions to take when the event occurs. Use an event handler to configure an action for your UI Builder page or the components on the page. For example: * Clicking a data visualization opens a list of records represented in the visualization * Fetching data successfully for a list opens an alert that indicates the data fetch was successful * Selecting a radio button adjusts the filter for a list on the page * Loading a page opens a modal to confirm acceptance of cookies before proceeding {#work-events__ul_uql_4hb_1zb} When you add an event handler to a UI Builder page or component, you can choose different types of event handlers. For example, a Button component can have the following types of event handlers: * Inherited event handlers. An inherited event handler is exposed from the page that you are working in. If you are in the parent UI Builder page, an inherited event handler could be exposed from the app shell. The following table lists the different types of inherited event handlers that you can use and what you can do with them.{#work-events__table_uwz_1py_24b__entry__2} | Event handler | Description | |-|-| | Breadcrumb URL changed | | | Link to destination | Navigate to a destination. * App routes: Link to another page within an app, like a home screen. * External URL: Link to a website or any external URL. {#work-events__ul_gj4_3py_24b} Sample script return { route: null, /* Page route, e.g. 'record' */ fields: null, /* Required params, e.g. {"table":"incident","sysId":"X"} */ params: null, /* Optional params, e.g. {"selectedIndex" : 1} */ ☑️redirect: null, /* ??? True/false? */ ☑️passiveNavigation: null, /* Load in background, e.g. 'false' */ title: null, multiInstField: null, ☑️targetRoute: null, /* ??? */ ☑️external: null /* ??? True/false? */ }; | | Add parameters to URL | Add additional parameters to a URL. Sample script { "selectedTabIndex" : 0 } | | Open or close modal dialog | After you create a modal, use Open or close modal dialog to trigger the modal. | [Table 1. Inherited event handlers] {#work-events__table_uwz_1py_24b} * Page-level event handlers. This type of event handler is common to all pages, and you would use this handler type when you want to add or clear page-level alert notifications. The following table lists the different types of page-level event handlers that you can use and what you can do with them.{#work-events__table_xdx_dqy_24b__entry__2} | Event handler | Description | |-|-| | Add alert notifications | Add a code snippet to send an alert notification. For example: return { items: [{"type" : "info", "message" : "Info message", "id" : "optionalID"}] /* Types: info, warning, error */ }; | | Remove alert notification | Add code to call alert notification IDs that you want to dismiss. For example, click a button to remove a page load alert notification. | | Clear alert notification | Add code to call all alert notification IDs that you want to dismiss. For example, click a button to remove all alert notifications. | | Set loading state | Toggle loading on or off. For example, you can toggle loading on to load the page when you click a button or toggle loading off to not load the page when a button is clicked. | | Update client state parameter | Declaratively set the client state parameter. Let's say that you have a client state parameter that you set up with a value. You can configure the Update client state parameter event handler to update the client state parameter with a new value. For example, you have a client state parameter that is called Greeting that is set up with Hello as the initial value. You can add an Update client state parameter event handler, select the Greeting client state parameter, and then enter a new value like Goodbye. When you click the button, Goodbye replaces Hello on the page. | | UXF macroponent viewport load requested | Add to a component, such as a button component, to open a viewport. For more information, see [Add a viewport component to your page](https://www.servicenow.com/docs/oSC0LHULaJjBPqQbDvOCXQ "Add a viewport component to your page and create a subpage to create separate content on the page."). | [Table 2. Page-level event handlers] {#work-events__table_xdx_dqy_24b} * Data resource handlers. This type of event handler triggers the fetching or writing of data to the server. You can refresh the app shell data source data on your UI Builder page by clicking a button. For example, with a data resource handler, you can do the following actions: * Bind data to the description of an incident record. * Change the value of the incident description. * Add a button component to your page. * Label the button as Refresh incident. * Add a Look Up Record event handler for the button. * Save your page. * If the description of the incident record changes, click Refresh to update the description on your page. {#work-events__ul_cvj_jxy_24b} * Client scripts. Scripts that execute when an event is triggered on a component. You create these scripts in the Client scripts section in UI Builder. For more information, see [Define and bind client scripts to components](https://www.servicenow.com/docs/m_zkEwTZDHkzCWbhi4XjZQ "Add and edit client scripts in UI Builder so that you can update the client state through events. You can bind these scripts to any component by using an event handler."). {#work-events__ul_wzp_qdc_snb} ## Binding events to components in UI Builder {#work-events__section_qll_2fb_snb} Bind event handlers to the events on a component. When you add components to your UI Builder page, these components are not configured to perform any action on your page. For example, a button component is static and does not do anything until you bind an event action to it, such as deleting a record. Some components have several events where event handlers can be assigned. For example, on the list component, you can assign a navigation handler to the Row clicked event. You can also assign an open modal to the Data fetch failed event. For more information, see [Bind an event to a component](https://www.servicenow.com/docs/R2RMf3UPRESlc4qhPs0Pyg "Bind data elements within UI Builder so that you can add event actions to your components."). ## Binding events to UI Builder pages {#work-events__section_upz_rfd_snb} Bind a page-level event to execute event handlers on the page. For example, use page-level events for page notifications, page load, or when a page property changes. The assignment of the event handler to the page-level event is similar to assigning handlers to events from components. You can bind event mappings using the following methods: * Page event mappings. Add, remove, or clear alert notifications on your page. * Variant event mappings. Add, remove, or clear alert notifications on your page variant. * Dispatched events. Create dispatched events for your page to create relayed event mappings that model events after a parent event handler. Select a target parent event handler to model the payload fields after it. * Handled events. Add a handled event for an event that is exposed and available for use by other users. {#work-events__ul_sfg_njg_14b} For more information, see [Bind an event to a page](https://www.servicenow.com/docs/HOhlFGW48hGMQqtbY62L7g "Use page event mappings to bind data elements within UI Builder so that you can add event actions to your page."). ## Binding events to data resources in UI Builder {#work-events__section_ztd_sfd_snb} Bind event handlers to individual data resources on your UI Builder page. For example, when a data resource successfully fetches new data, it executes an event handler, like navigation, to take a user to the next step in a flow. When a data resource successfully adds a record to a table, it shows a success modal that uses the show modal event handler. For more information, see [Bind an event to a data resource](https://www.servicenow.com/docs/GuXzDJR7VFCoZLTSVq8Btw "Assign event handlers within UI Builder to individual data resources on your page. When a data resource successfully fetches new data, it executes an event handler to take a user to the next step in a flow."). ## Binding events to declarative actions in UI Builder {#work-events__section_vm2_sfd_snb} Bind data elements to add event actions to a declarative action definition in Actions \& Components in the ServiceNow AI Platform®. For example, you could bind a data element to add an event action to complete work on a table. If you add a component to your UI Builder page that has a declarative action, you must bind it to a handled event. The handled event creates an action that is performed when a user selects the component. By selecting Configure declarative action event mapping, you add a new event handler to define what the declarative action does on the page. For more information, see [Bind an event to a declarative action](https://www.servicenow.com/docs/xQbtGUNzVV0lFHscHNTsJA "Bind data elements within UI Builder so that you can add event actions to a declarative action."). * **[Define map events](https://www.servicenow.com/docs/L481ot9Gs_fiR0O8y_KViw)** An event mapping in UI Builder is the process that enables you to map an event's payload or contextual values to the object or handler that acts on that event. The four event types are: component, page, data resource, and declarative action. * **[Event payloads in UI Builder](https://www.servicenow.com/docs/wEAWynMYdK7Cw58faIAR5w#event-payloads)** Use event payloads to link data to an action. * **[Configure an event handler manually](https://www.servicenow.com/docs/G3BbAPtifzGm3ibWmNnJ_w)** Add an event handler to a page, component, data resource, or declarative action within UI Builder so that your user can trigger an action. * **[Configure an event handler with Now Assist](https://www.servicenow.com/docs/~iXgWWojV7xyWbCs7stZ7A)** Use Now Assist in UI Builder to configure event handlers. At present, you can configure link to destination, open or close modal, and view load requested event handlers using Now Assist in UI Builder. * **[Bind events to add actions](https://www.servicenow.com/docs/lMdTz3GsfTuZ2muGAyHbBg)** After you have created events, you can bind them to actions on your components, pages, data resources, and declarative actions. * **[Disable component preset event mappings](https://www.servicenow.com/docs/p~ChuYrb2VRafU0WEJE87w)** You can disable event mappings that are automatically created by a component preset. * **[Delete an event handler](https://www.servicenow.com/docs/f4jzHEpAoQlCprZF8BgXMQ)** Delete an event handler that you no longer need in UI Builder. * **[Delete an event mapping](https://www.servicenow.com/docs/HTge1Lt2Ex5uESk18gFo_A)** Delete an event mapping that you no longer need in UI Builder. * **[Add events to track components with unsaved changes](https://www.servicenow.com/docs/UYYrtIiBCfFHDWP56eFcSA)** Locate dirty state components through event configuration.