Skip to main content

The Utils JavaScript Library

JavaScript methods for interacting with apps.

Use the utils JavaScript API methods to perform actions and control behavior.

These methods are not available within transformers or workflows.

JavaScript API methods for this object. You can write JavaScript almost anywhere in Retool and use methods to manipulate data and property values.

utils.changeLocale​

Change the user's locale.

Definition
utils.changeLocale(locale)
Parameters

locale​

The locale.

Type string
Format Plain Text
Examples
"en"
Examples

Change the locale to en.

utils.changeLocale('en');

utils.confetti​

Display a confetti animation.

Definition
utils.confetti()
Examples

Display a confetti animation.

utils.confetti();

utils.copyToClipboard​

Copy the specified data to the clipboard.

Definition
utils.copyToClipboard(data)
Parameters

data​

The data to copy, formatted as a string.

Type string
Examples

Copy the value of textInput1.value to the clipboard.

utils.copyToClipboard(textInput1.value);

utils.downloadFile​

Download the specified data as a file. data can be a string for plain text data or an object containing base64-encoded binary data.

Definition
utils.downloadFile(data, fileName, fileType)
Parameters

data​

The data to export. Can be either a string value or an object that contains base64-encoded data.

Type string | object
Object Properties

base64Binary​

The base64-encoded data.

Type string

fileName​

The file name.

Type string

fileType​

The file extension.

Type string
Examples

Download a text file.

utils.downloadFile('Hello World', 'hello-world', 'txt');

Download a JPEG file.

utils.downloadFile({data: {base64Binary: 'iVBORw0KGgoAAAANSU...'}}, 'image', 'jpeg');

utils.downloadPage​

Export and download a PDF of the current view for the app in the browser.

Definition
utils.downloadPage(options)
Parameters

options​

The options for the PDF export.

Type object
Object Properties

componentsToExclude​

A list of component names to exclude.

Type array
Array values string

componentsToInclude​

A list of CSS selectors to include.

Type array
Array values string

fullscreen​

Whether to generate a PDF using presentation mode. Defaults to false.

Type boolean

scale​

The resolution of the generated PDF. Defaults to the value for window.devicePixelRatio.

Type number

selectorsToExclude​

A list of CSS selectors to exclude.

Type array
Array values string

selectorsToInclude​

A list of CSS selectors to include.

Type array
Array values string

utils.exportData​

Exports data as a file in a CSV, TSV, JSON, or Excel format.

Definition
utils.exportData(options)
Parameters

options​

The options for the export.

Type object
Object Properties

data​

The data.

Type string | number | boolean | object | array
Format Custom data

fileName​

The file name.

Type string

fileType​

The file extension.

Type string

utils.getCurrentPosition​

Retrieves the user's current geographical location, if allowed by the user. This method returns a promise and can only be used in JavaScript queries, not in transformers or {{ }} dynamic expressions.

Definition
await utils.getCurrentPosition()
Returns

Returns a Promise that resolves to the following:

coords​

User location data.

Type object
Object Properties

accuracy​

The location accuracy, in meters.

Type number

altitudeAccuracy​

The altitude accuracy, in meters.

Type number

heading​

The direction of travel, in degrees from true north.

Type number

latitude​

The latitudinal position.

Type number

longitude​

The longitudinal position.

Type number

speed​

The velocity, in meters per second.

Type string

timestamp​

The timestamp on which location information was retrieved.

Type number
Format Timestamp
Examples
1617024000000
Examples

Get the user's current position.

utils.getCurrentPosition();

utils.getDataByObjectURL​

Converts the contents of a blob: or file:// URL to a Base64-encoded string. Returns a Base64-encoded string.

Definition
utils.getDataByObjectURL(data)
Parameters

data​

The data to convert.

Type string

utils.openApp​

Navigates to another Retool app within the organization.

Definition
utils.openApp(uuid, options)
Parameters

uuid​

The UUID (Universally Unique Identifier).

Type string
Format UUID

options​

The options for navigating to another app.

Type object
Object Properties

pageName​

The name of the page to navigate to.

Type string

hashParams​

An array of URL hash parameters in the current URL.

Type object
Formatobject
Object Properties

key​

The key of the hash parameter.

Type string

value​

The value of the hash parameter.

Type string
Examples
{
"key": "id",
"value": "1234567890"
}

newTab​

Whether to open in a new tab. Performs client-side routing if false. Defaults to false.

Type boolean

queryParams​

Key-value pairs to include as URL query parameters.

Type object
Object Properties

key​

The key of the query parameter.

Type string

value​

The value of the query parameter.

Type string
Examples
{
"key": "id",
"value": "1234567890"
}

utils.openPage​

Navigates to another page within the app.

Definition
utils.openPage(pageName, options)
Parameters

pageName​

The name of the page to navigate to.

Type string

options​

The options for navigating to another page.

Type object
Object Properties

passDataWith​

The data to pass with the page open.

Type string
Allowed Values
ValueDescription
urlParams
globalVariable

queryParams​

Key-value pairs to include as URL query parameters.

Type object
Object Properties

key​

The key of the query parameter.

Type string

value​

The value of the query parameter.

Type string
Examples
{
"key": "id",
"value": "1234567890"
}

hashParams​

An array of URL hash parameters in the current URL.

Type object
Formatobject
Object Properties

key​

The key of the hash parameter.

Type string

value​

The value of the hash parameter.

Type string
Examples
{
"key": "id",
"value": "1234567890"
}

globalVariable​

The name of the global variable.

Type string

setInOrSetValue​

When passing data using a variable, the method to use to set the data.

Type string
Allowed Values
ValueDescription
Set in
Set value

keyPath​

A list of key names that represent the hierarchical structure of a variable object when setting a value. The last item is the key on which the value is set.

Type array
Array values string

globalVariableValue​

The value.

Type string | number | boolean | object | array

persistUrlParams​

Whether to persist URL parameters when navigating to a new page.

Type boolean

newTab​

Whether to open in a new tab. Performs client-side routing if false. Defaults to false.

Type boolean

utils.openUrl​

Navigates to the specified URL.

Definition
utils.openUrl(url, options)
Parameters

url​

The URL.

Type string

options​

The options for navigating to a URL.

Type object
Object Properties

forceReload​

Whether to prevent client-side routing and force a page reload. Defaults to false.

Type boolean

newTab​

Whether to open in a new tab. Performs client-side routing if false. Defaults to false.

Type boolean

utils.playSound​

Plays an audio file at a specified URL. Supports all browser-compatible audio formats.

Definition
utils.playSound(url)
Parameters

url​

The URL.

Type string

utils.serializePage​

Serializes the current Retool page as a Base64-encoded PDF string. Returns the Base64-encoded string.

Definition
utils.serializePage()

utils.showNotification​

Display an in-app notification.

Definition
utils.showNotification(options)
Parameters

options​

The notification options.

Type object
Object Properties

body​

The notification body text.

Type string

duration​

The duration that the notification should remain visible, in seconds.

Type number

notificationType​

The notification type to display. notificationType also determines the notification color scheme. Defaults to info.

Type string
Allowed Values
ValueDescription
info

Info notification.

success

Success notification.

warning

Warning notification.

error

Error notification.

title​

The notification title.

Type string