Skip to main content

utils methods

JavaScript API methods for interacting with apps.

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

tip

util methods are not available within transformers.

utils.changeLocale()​

Change the current user's locale.

valuerequired
string

The locale to set. Supports ISO-639 language codes.

Example​

Change the current user's locale to en-US.

utils.changeLocale('en-US');

utils.confetti()​

Display confetti animation.

Example​

Display the confetti animation.

utils.confetti();

utils.copyToClipboard()​

Copies the given string to the user's clipboard.

valuerequired
string

The string to copy.

Example​

Copy the selected cell contents of table1 to the user's clipboard.

utils.copyToClipboard(table1.selectedCell.data);

utils.downloadFile()​

Generates a file containing the specified data which is then downloaded by the user's browser.

To download data from a Table component, use utils.exportData().

data
string | object

The data to download. To download Base64-encoded data, provide an object that contains the parameter base64Binary and encoded value.

base64Binaryrequired
string

The Base64-encoded data to download.

fileName
string

The downloaded file name. Defaults to file.

Examples​

Download the results of getUsersQuery as a YAML file named users-data.

utils.downloadFile(getUsersQuery.data, "users-data", "yaml");

utils.downloadPage()​

Generates a PDF file of the current view which is then downloaded by the user's browser. It excludes Custom, HTML, and IFrame components.

fileName
string

The downloaded file name. Defaults to file.

options
object

An object that controls selector and component inclusion or exclusion, and PDF formatting.

componentsToExclude
array

A list of components to exclude from the PDF.

componentsToInclude
array

Any components to include in the PDF. Excludes all other components.

fullscreen
boolean

Whether to download the page in presentation mode. Defaults to false.

scale
number

The resolution of the page to export. Defaults to window.devicePixelRatio.

selectorsToExclude
array

A list of selectors to exclude from the PDF.

selectorsToInclude
array

Any selectors to include in the PDF. Excludes all other selectors.

Example​

Download a PDF of the current view, excluding container1 and its nested components, as users_dashboard.pdf.

utils.downloadPage("users_dashboard", { componentsToExclude: ["container1"] });

utils.exportData()​

Generates a file containing data for the specified Table component which is then downloaded by the user's browser.

datarequired
object

The table data to export. Use utils.exportData() to reference a Table component's data, normalizedData, or displayedData.

fileName
string

The file name of the downloaded file. Defaults to export. If fileType is xlsx, fileName must adhere to Excel worksheet naming guidelines.

fileType
string

The file type for the downloaded file. Defaults to csv. If fileType is xlsx, fileName must adhere to Excel worksheet naming guidelines.

Example​

Download usersTable.data as a CSV named usersData.

utils.exportData(usersTable.data, "usersData");

utils.getCurrentPosition()​

Retrieves the user's current geographical location, if allowed by the user.

options
object

The Base64-encoded JSON file to parse.

onSuccessrequired
function

A callback function to trigger when the method runs successfully.

Return value​

Details
coords
object[]

A callback function to trigger when the method runs successfully.

Details
latitude
number

The position’s latitude in decimal degrees.

Details
longitude
number

The position’s longitude in decimal degrees.

Details
speed
string

The velocity in meters per second.

Details
accuracy
number

The position’s accuracy in meters.

Details
altitude
number

The position’s accuracy in meters.

Details
altitudeAccuracy
number

The position’s accuracy in meters.

Details
heading
number

The direction of travel in degrees from true north.

Details
timestamp
number

The date and time location information was retrieved, in UNIX time.

Example​

Retrieve the coordinates of the current user and calls updateMap upon success.

await utils.getCurrentPosition({
  onSuccess: function (data) {
    updateMap.trigger();
  },
});

utils.getDataByObjectURL()​

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

valuerequired
string

The blob or URL to convert.

Example​

Convert a captured signature image to a Base64-encoded string and pass it to a SQL query using additionalScope.

const base64Data = await utils.getDataByObjectURL(signature1.value);

sqlQuery1.trigger({ additionalScope: { base64Data } });

utils.openApp()​

Opens a Retool app. The app must be in the same organization as the caller of openApp.

appUuidrequired
string

The unique identifier of the Retool app to open. Available in retoolContext.

options
object

Additional configuration options.

queryParams
object[]

A list of query parameters to include when opening the app.

newTab
boolean

Whether to open the app in a new tab. Defaults to true.

Example​

Open an app with the query parameters source=updateUsersApp.

utils.openApp("371ac2f8-3aaf-11ed-8b80-836b0df4638d", {
  queryParams: { source: "updateUsersApp" },
});

utils.openUrl()​

Open the specified URL.

urlrequired
string

The URL to open.

options
object

Additional configuration options.

forceReload
boolean

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

newTab
boolean

Whether to open the URL in a new tab. Defaults to true.

Example​

Open Retool Docs in the current tab.

utils.openUrl("https://docs.retool.com", { newTab: false });

utils.playSound()​

Plays the specified sound.

urlrequired
string

The URL for a sound asset to play (e.g., an .mp3 file).

Example​

Plays the success.mp3 file.

utils.playSound('https://s3-us-west-2.amazonaws.com/s.cdpn.io/3/success.mp3')

utils.serializePage()​

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

options
object

Additional configuration options.

selectorsToExclude
array

An array of CSS selectors to exclude from the serialized page.

componentsToExclude
array

An array of components to exclude from the serialized page.

selectorsToInclude
array

An array of CSS selectors to include in the serialized page.

componentsToInclude
array

An array of components to include in the serialized page.

scale
number

The resolution of the serialized page. Defaults to window.devicePixelRatio.

Example​

Serializes the current view, excluding container1 and its nested components.

let pdf = await utils.serializePage({ componentsToExclude: ["container1"] });

utils.showNotification()​

Shows a notification message on the top right corner of the screen.

options
object

Optional configuration for the notification.

title
string

The notification title. Defaults to Notification.

description
string

The notification text.

notificationType
'info' | 'success' | 'warning' | 'error'

The notification type. Defaults to info.

duration
number

The length of time, in seconds, to display the message. Defaults to 4.5.

Example​

Display a success message after deleting a user.

utils.showNotification({
  title: "Deleted user",
  description: "Successfully deleted user.",
  notificationType: "success",
  duration: 3,
});