---
sourceDocument: Zurich ServiceNow AI Platform user interface
sourceDocumentLink: https://www.servicenow.com/docs/r/zurich/platform-user-interface

 Release :

    - zurich

ft:locale :

    - en-US

ft:publication_title :

    - Zurich ServiceNow AI Platform user interface

ft:clusterId :

    - platux

bundleId :

    - platux

workflow :

    - Platform


---

# Developing custom widgets

# Developing custom widgets {#ariaid-title1}

Release version: Zurich  
Updated July 31, 2025  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 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 Developing custom widgets

This guide explains how ServiceNow customers can develop custom widgets for Service Portal pages using AngularJS, Bootstrap, and the ServiceNow API.
Widgets enable you to create dynamic, reusable components that enhance user interactions and portal functionality.
Show full answer Show less  
Developing widgets requires knowledge of the ServiceNow API for server-side record operations and AngularJS for client-side data binding, user input handling, and DOM manipulation. Optionally, you can leverage Bootstrap for styling and components.

## Key Widget Components

* **HTML Template (mandatory):** Defines the dynamic view users interact with, using AngularJS to bind data and collect input.
* **Client Script (mandatory):** Acts as the client controller, processing data before rendering, mapping server data to client objects, and sending user input back to the server.
* **Server Script (mandatory):** Handles server-side logic such as initializing widget state, querying records, and sending data to the client script.
* **Link Function (optional):** Allows direct DOM manipulation on the client side using AngularJS.
* **Option Schema (optional):** Enables portal administrators to configure widget parameters, facilitating flexible and reusable widget instances.
* **Angular Providers (optional):** Support shared context, state persistence, and reusable behaviors across multiple widgets to optimize performance and maintainability.
* **Dependencies (optional):** Reference external JavaScript or CSS resources, enabling integration with third-party libraries and styles.

## Widget Data Flow and Global Objects

When rendering a widget, the server script executes first, initializing three global objects: **input** (data from client), **options** (widget configuration), and **data** (server data sent to client). The client script accesses server data through `c.data` and sends updates back via `server.update()`. The `c.options` object provides read-only access to widget invocation parameters.

## Development Tools and Best Practices

* **Widget Editor:** Use this IDE-like environment within Service Portal Configuration to script, preview, and manage widget components efficiently.
* **ECMAScript 2021 Support:** You can enable modern JavaScript syntax for server-side scripts if your application standards allow.
* **General Guidelines:** Follow best practices for performance, scalability, and user experience when creating custom widgets.
* **Reuse and Extend:** Clone existing widgets to accelerate development or build from scratch for tailored functionality.

## Additional Features and Use Cases

* **Option Schema:** Define configurable parameters for each widget instance to enable personalized portal experiences.
* **Angular Providers:** Maintain state and shared data across widgets, promoting efficient and maintainable code.
* **Embedded Widgets:** Insert widgets within HTML templates or scripts for modular functionality.
* **Widget Dependencies:** Link external JavaScript and CSS resources to enrich widget capabilities.
* **Internationalization:** Tag strings for translation in widget fields to localize portal content.
* **Replacing UI Macros:** Use widgets to modernize Service Catalog forms by replacing UI Macros with reusable widget code.
* **Troubleshooting:** Utilize provided tools to diagnose and resolve widget behavior issues.
* **Embeddables:** Integrate UI Builder components into Service Portal and other platforms without AngularJS rebuilds, enabling low-code configuration and cross-platform reuse.

## Practical Benefits for ServiceNow Customers

By developing custom widgets, you can tailor your Service Portal to meet unique business needs, improve user engagement, and streamline service delivery. Leveraging AngularJS and the ServiceNow API ensures powerful client-server interactions, while optional components like Angular Providers and option schemas promote reusable, maintainable widgets. The Widget Editor and best practices reduce development time and enhance quality. Additionally, internationalization support and embeddables extend your portal's reach and flexibility.  
Develop custom widgets for portals using AngularJS, Bootstrap, and the ServiceNow API.

## Before you begin {#widget-dev-guide__section_xrx_qf2_kz}

To develop widgets, you need ServiceNow API experience to:

* Run record queries on the server.
* Create and update records.
{#widget-dev-guide__ul_bs4_rch_j1b}  
You need AngularJS experience to:

* Bind variables to client controllers.
* Access server objects in a widget.
* Gather user input.
{#widget-dev-guide__ul_hmf_5ch_j1b}

Optionally, you can build on the Bootstrap template by accessing Bootstrap components.

## Parts of a widget {#widget-dev-guide__section_gpd_lkw_h1b}

Like Angular directives, widgets execute a specified behavior within a Service Portal page. A widget includes
mandatory and optional scripting components.  

HTML template

:   A mandatory widget component.

    The HTML template requires knowledge of AngularJS to display and gather data. Use the HTML
    template to:  
    * Render the dynamic view that a user sees in the browser using information from the model and controller.
    * Bind client script variables to your markup.
    * Gather data from the end user.
    {#widget-dev-guide__ul_chb_mdh_j1b}

Client script

:   A mandatory widget component.

    A client script requires knowledge of both the ServiceNow API and AngularJS to create a
    client controller. Use the client script to:  
    * Map server data from JavaScript and JSON objects to client objects.
    * Process data before rendering it.
    * Pass data to the HTML template.
    * Pass user input and data back to the server for processing.
    {#widget-dev-guide__ul_elh_d2h_j1b}

Server script

:   A mandatory widget component.

    A server script requires knowledge of the ServiceNow API to work with record data.
    Use the server script to:  
    * Set the initial state of the widget.
    * Send record data to the widget client script using the data variable.
    * Run server-side queries.
    {#widget-dev-guide__ul_n5p_42h_j1b}

Link function

:   An optional widget component.

    The link function requires knowledge of AngularJS. Use a link function to directly
    manipulate the DOM.

Option schema

:   An optional widget component.

    Allows a Service Portal admin to
    configure a widget. Use the option schema to:  
    * Specify the parameters for a widget.
    * Allow admin users to define instance options for a widget instance.
    * Develop flexible, reusable widgets.
    {#widget-dev-guide__ul_cmx_w3h_j1b}

Angular Providers

:   An optional widget component.

    Angular Providers require knowledge of AngularJS. Use Angular Providers to:  
    * Keep widgets in sync when changing records or filters.
    * Share context between widgets.
    * Maintain and persist state.
    * Create reusable behaviors and UI components and inject them into multiple widgets.
    {#widget-dev-guide__ul_mm2_2zq_yz}

Dependencies

:   An optional widget component.

    A widget dependency is an external resource used by your widget such as JavaScript or CSS
    files.

## Global objects in widgets {#widget-dev-guide__section_rsq_g1h_j1b}

When a widget begins to render for the first time on a page, the server script executes first
and accesses three global objects: input, options,
and data. Because the input variable is a data
object sent from the client script, this variable is undefined when first initialized.

When a widget is first instantiated, the server script:  
1. Initializes an empty data object.
2. Initializes the input object with any data sent from the client controller, or the options object with any data used to initialize the widget.
3. Sends the data object to the client controller as JSON.
{#widget-dev-guide__ol_sh3_btw_xz}

The client script:  
1. Accesses the server data object using `c.data`.

   Note:  
   By default, widgets use the c variable to represent the controller instance using `controller as` syntax. You can change this variable when creating or cloning widgets.
2. Uses `server.update()` to post changes to the data model. This method
   updates the server script using the input object.

   Note:  
   After calling `server.update()`, the client script data object is automatically overwritten by the server script data object.
3. Uses `c.options` to access the values used to invoke the widget on the server. This object is read-only.
{#widget-dev-guide__ol_mjs_jtw_xz}

## Using the Widget Editor {#widget-dev-guide__section_dsy_kch_j1b}

When you create a widget, a record is created in the sp_widget table. However, you can use the Widget Editor in Service Portal Configuration as your scripting environment. The Widget Editor is a full page application similar to an IDE. You can show the parts of the widget you want to edit and hide the rest, while
previewing your changes in real time.  
Note:  
For server-side scripts, you can turn on using the ECMAScript 2021 (ES12) JavaScript mode if your application uses ES5 Standards mode or Compatibility mode. Scripts in applications with the JavaScript mode set to ECMAScript 2021 (ES12) use ECMAScript 2021 (ES12) by default. For more information, see [Turn on ECMAScript 2021 (ES12) mode for a script](https://www.servicenow.com/docs/access?context=set-es12-mode-scripts&version=zurich&pubname=zurich-api-reference&ft:locale=en-US).

<br />

* **[General guidelines for developing widgets](https://www.servicenow.com/docs/6IjU23b411otA_o1eOx23Q)**   
  When developing custom widgets, keep these general guidelines in mind for optimal performance, scalable development, and a good user experience.
* **[Tutorial: Build a custom widget](https://www.servicenow.com/docs/oB3wdMjxpTkqH5rEKdIDDw#adv-widget-tutorial)**   
  Follow this tutorial to build a custom widget that displays Service Catalog items. Use this tutorial as a model to help you understand the advanced scripting power of the Service Portal.
* **[Clone a widget](https://www.servicenow.com/docs/zp2rp1ncHgD287W05TnDLw)**   
  Take advantage of existing code by cloning and editing an existing widget.
* **[Create a new widget](https://www.servicenow.com/docs/2RPJ5mRdkR06hcwhD1dFcw)**   
  Create a new widget to build a custom widget from scratch.
* **[Widget option schema](https://www.servicenow.com/docs/0WFFduPkc8hQMA3VIINvOw#c_WidgetInstanceOptions)**   
  Widget instances allow users to uniquely configure each widget they add to a page. Use the option schema to define the parameters for your widget.
* **[Widget API reference](https://www.servicenow.com/docs/8g1SLJcHjcOsc1OLZ6567g#widget-api-reference)**   
  Service Portal includes client and server side APIs to use in widget client and server scripts.
* **[Reuse components with Angular Providers](https://www.servicenow.com/docs/fjzhjkpr_cPGn1zMVe33gw)**   
  Angular Providers are reusable components that can be injected into multiple widgets. To ensure quick loading widgets and a high performing portal, create Angular Providers instead of overloading your client controllers with persistent data and additional logic. With Angular Providers, you can maintain data for the lifetime of your Service Portal and reuse components and data objects across multiple widgets.
* **[Embedded widgets](https://www.servicenow.com/docs/r7fqzMxrQC2fW_a_oQ66dg#c_NestedWidgets)**   
  Embed a widget in the HTML template, server script, or client script.
* **[Create a widget dependency](https://www.servicenow.com/docs/gdwM4drpHXjnWD1L7NhApA)**   
  In Service Portal, you can link JavaScript and CSS files to widgets to create dependencies between widgets and third-party libraries, external style sheets, and angular modules.
* **[Internationalize a widget](https://www.servicenow.com/docs/H2EOX_UG3ylnUyI2QpuQ8g)**   
  Use the `${}` or `gs.getMessage()` syntax in the HTML Template, Client Script, or Server Script fields of a widget to tag strings for translation so you can localize your Service Portal content.
* **[Replace a Service Catalog form script with a widget](https://www.servicenow.com/docs/tvRvqRbeIt3HzKaCN1TSLw)**   
  You can use widgets in Service Portal to replace UI Macros. If your Service Catalog form includes a UI Macro that references other fields or variables on the form, you can create a widget to hold reusable code and embed it within the Service Catalog form. Use special syntax to access any variable fields on the form.
* **[Widget troubleshooting guide](https://www.servicenow.com/docs/kX4IN2fwrUNAKYXpkY_6ag)**   
  Use the following tools to investigate and resolve unexpected behavior in your custom Service Portal widgets.
* **[Embeddables in Service Portal](https://www.servicenow.com/docs/nLinOv60jibYxeW1zlsSAA)**   
  Embeddables are UI Builder components that you can embed into Service Portal pages, external websites, and other web interfaces. Using embeddables, you can reuse existing components across multiple platforms without requiring an AngularJS rebuild. Embeddables enable low-code configuration of components, reducing development time and improving integration flexibility across your ServiceNow® ecosystem.

