@servicenow/sdk/docs/api/clientscript-api.md

ServiceNow SDK

---
tags: [ClientScript, client script, browser script, sys_script_client, onLoad, onChange, onSubmit, onCellEdit, form script, g_form]
---
# ClientScript

Creates a Client Script (`sys_script_client`) that runs JavaScript in the browser on form events (onLoad, onChange, onSubmit, onCellEdit) to dynamically configure forms, fields, and field values.

## Signature

```typescript fluent
ClientScript(properties)
```

## Parameters

### properties

`ClientScriptProps<keyof Tables, client_script_events, G>`

**Properties:**

- **$id** (required): `string | number | ExplicitKey<string>`

- **name** (required): `string`
  Name of the client script

- **table** (required): `keyof Tables`
  Name of the table on which the client script runs

- **$meta** (optional): `object`
  - **installMethod**: `'first install' | 'demo' | 'once'`
    Map a record to an output folder that loads only in specific circumstances.
    'first install' - > 'unload',
    'demo' -> 'unload.demo'


- **active** (optional): `boolean`
  Whether the record is enabled

- **appliesExtended** (optional): `boolean`
  Indicates whether the client script applies to tables extended from the specified table

- **description** (optional): `string`
  Description of the functionality and purpose of the client script

- **field** (optional): `field_type<keyof Tables, client_script_events>`
  Field on the table that the client script applies to.
  This property applies only when the type property is set to `onChange` or `onCellEdit`.

- **global** (optional): `G`
  Indicates which views of the table the client script runs.
  - `true`: the script runs on all views
  - `false`: the script runs only on specified views

- **isolateScript** (optional): `boolean`
  Indicates whether scripts run in strict mode, with access to direct DOM, `jQuery`, `prototype`, and the `window` object turned off

- **messages** (optional): `string`
  Strings that are available to the client script as localized messages using `getmessage('[message]')`.

- **script** (optional): `string`
  Script to be executed when the client script runs

- **type** (optional): `client_script_events`
  Type of client script, which defines when it runs

- **uiType** (optional): `'desktop' | 'all' | 'mobile_or_service_portal'`
  User interface to which the client script applies

- **view** (optional): `G extends false ? string : never`
  Views of the table on which the client script runs.
  This property applies only when the `global` property is set to `false`


## See

- https://docs.servicenow.com/csh?topicname=client-script-api-now-ts.html&version=latest


## Examples

### OnLoad Client Script with Inline Script

Create an onLoad client script with inline JavaScript code

```typescript fluent
/**
 * @title OnLoad Client Script with Inline Script
 * @description Create an onLoad client script with inline JavaScript code
 */
import { ClientScript } from '@servicenow/sdk/core'
ClientScript({
    $id: Now.ID['cs0'],
    name: 'my_client_script',
    table: 'incident',
    appliesExtended: false,
    global: true,
    uiType: 'all',
    description: 'Custom client script generated by Now SDK',
    messages: '',
    isolateScript: false,
    type: 'onLoad',
    script: `function onLoad() {
        g_form.addInfoMessage("Table loaded successfully!!")
    }`,
})

```

### OnChange Client Script

Create a client script that triggers when a field value changes

```typescript fluent
/**
 * @title OnChange Client Script
 * @description Create a client script that triggers when a field value changes
 */
import { ClientScript } from '@servicenow/sdk/core'
ClientScript({
    $id: Now.ID['onchange_script'],
    name: 'field_change_handler',
    table: 'incident',
    type: 'onChange',
    field: 'priority',
    uiType: 'desktop',
    description: 'Handles priority field changes',
    script: `function onChange(control, oldValue, newValue, isLoading) {
        if (isLoading) return;
        if (newValue === '1') {
            g_form.addWarningMessage('High priority incident - please add urgency details');
        }
    }`,
})

```

### OnLoad Client Script with External File

Create an onLoad client script that uses an external JavaScript file

```typescript fluent
/**
 * @title OnLoad Client Script with External File
 * @description Create an onLoad client script that uses an external JavaScript file
 */
import { ClientScript } from '@servicenow/sdk/core'

export default ClientScript({
    $id: Now.ID['sample1'],
    type: 'onLoad',
    uiType: 'all',
    table: 'incident',
    global: true,
    name: 'sample_client_script',
    appliesExtended: false,
    description: 'sample client script',
    isolateScript: false,
    script: Now.include('../../server/ClientScript/clientscript-onload.client.js'),
})

```

**clientscript-onload.client.js**

```javascript
function onLoad() {
    g_form.addInfoMessage('Hello from Fluent Client Script')
}
```

For guidance on client script types, form events, and common patterns, see the `client-script-guide` topic.