The Utils JavaScript Library

Classic apps

You're viewing documentation for classic apps, which use Retool's original app editor. The new app builder is the recommended way to build apps and where Retool focuses new development.

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

Caution

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	array
Format	array
Array values	object

Array 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`

An array of key-value pairs to include as URL query parameters.

Type	array
Array values	object

Array 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

Value	Description
`urlParams`
`globalVariable`

`queryParams`

An array of key-value pairs to include as URL query parameters.

Type	array
Array values	object

Array 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	array
Format	array
Array values	object

Array 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

Value	Description
`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.setUrlParameters`

Set URL search parameters and hash parameters.

Definition
utils.setUrlParameters(queryParams, hashParams)

Parameters

`queryParams`

An array of key-value pairs to include as URL query parameters.

Type	array
Array values	object

Array 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	array
Format	array
Array values	object

Array 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"
} ]

`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

Value	Description
`info`	Info notification.
`success`	Success notification.
`warning`	Warning notification.
`error`	Error notification.

`title`

The notification title.

Type

string

utils.changeLocale​

locale​

utils.confetti​

utils.copyToClipboard​

data​

utils.downloadFile​

data​

base64Binary​

fileName​

fileType​

utils.downloadPage​

options​

componentsToExclude​

componentsToInclude​

fullscreen​

scale​

selectorsToExclude​

selectorsToInclude​

utils.exportData​

options​

data​

fileName​

fileType​

utils.getCurrentPosition​

coords​

accuracy​

altitudeAccuracy​

heading​

latitude​

longitude​

speed​

timestamp​

utils.getDataByObjectURL​

data​

utils.openApp​

uuid​

options​

pageName​

hashParams​

key​

value​

newTab​

queryParams​

key​

value​

utils.openPage​

pageName​

options​

passDataWith​

queryParams​

key​

value​

hashParams​

key​

value​

globalVariable​

setInOrSetValue​

keyPath​

globalVariableValue​

persistUrlParams​

newTab​

utils.openUrl​

url​

options​

forceReload​

newTab​

utils.playSound​

url​

utils.serializePage​

utils.setUrlParameters​

queryParams​

key​

value​

hashParams​

key​

value​

utils.showNotification​

options​

body​

duration​

`utils.changeLocale`

`locale`

`utils.confetti`

`utils.copyToClipboard`

`data`

`utils.downloadFile`

`data`

`base64Binary`

`fileName`

`fileType`

`utils.downloadPage`

`options`

`componentsToExclude`

`componentsToInclude`

`fullscreen`

`scale`

`selectorsToExclude`

`selectorsToInclude`

`utils.exportData`

`options`

`data`

`fileName`

`fileType`

`utils.getCurrentPosition`

`coords`

`accuracy`

`altitudeAccuracy`

`heading`

`latitude`

`longitude`

`speed`

`timestamp`

`utils.getDataByObjectURL`

`data`

`utils.openApp`

`uuid`

`options`

`pageName`

`hashParams`

`key`

`value`

`newTab`

`queryParams`

`key`

`value`

`utils.openPage`

`pageName`

`options`

`passDataWith`

`queryParams`

`key`

`value`

`hashParams`

`key`

`value`

`globalVariable`

`setInOrSetValue`

`keyPath`

`globalVariableValue`

`persistUrlParams`

`newTab`

`utils.openUrl`

`url`

`options`

`forceReload`

`newTab`

`utils.playSound`

`url`

`utils.serializePage`

`utils.setUrlParameters`

`queryParams`

`key`

`value`

`hashParams`

`key`

`value`

`utils.showNotification`

`options`

`body`

`duration`