Skip to main content

The Utils JavaScript Library

JavaScript methods for interacting with apps.

Version: Self-hosted 3.148 Stable

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.

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​

(No description available)

Type object
Object Properties

pageName​

The name of the page to navigate to.

Type string

hashParams​

The value to append as a hash parameter. Only one hash property can be included but it can contain multiple key-value pairs.

Type object

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

utils.openPage​

Navigates to another page within the app.

Definition
utils.openPage(pageName)
Parameters

pageName​

The name of the page to navigate to.

Type string

utils.openUrl​

Navigates to the specified URL.

Definition
utils.openUrl(url, options)
Parameters

url​

The URL.

Type string

options​

(No description available)

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