JavaScript API methods for interacting with the Retool app interface.
Methods
Use these methods to interact with the Retool app interface in queries and components. Note that these methods are not available within transformers.
utils.confetti()
Shows confetti animation.
Syntax
utils.confetti()
Return value
None.
Example
Show the confetti animation.
utils.confetti();
utils.copyToClipboard()
Copies the given string to the user's clipboard.
Syntax
utils.copyToClipboard(value)
value required
A string to specify the content to copy.
Return value
None.
Example
Copy table1's selected cell contents 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.
Syntax
utils.downloadFile(data, fileName, fileType)
data required
A string or object to specify the data to download. To download Base64-encoded data, provide an object that contains the parameter base64Binary with the Base64-encoded value.
fileName optional
A string to specify the downloaded file name. Defaults to "file" if not set.
Return value
None.
Examples
Download the results of getUsersQuery as a YAML file named users-data.
utils.downloadFile(getUsersQuery.data, "users-data", "yaml");
Download BASE64_STRING as a CSV file named users-data.
utils.downloadFile({ base64Binary: BASE64_STRING }, "users-data", "csv");
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.
Syntax
utils.downloadPage(fileName, options)
fileName optional
A string to specify the name of the downloaded file.
options optional
An object that controls the PDF formatting and selectors and components to exclude.
| Parameter | Type | Description |
|---|---|---|
selectorsToExclude | array (optional) | Any selectors to exclude from the PDF. |
componentsToExclude | array (optional) | Any components to exclude from the PDF. |
scale | number (optional) | The resolution of the page to export. Defaults to window.devicePixelRatio. |
fullScreen | boolean (optional) | Whether to download the page in presentation mode. Defaults to false. |
Return value
None.
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.
Syntax
utils.exportData(data, fileName, fileType)
data required
An object or array containing the table data to export. data can be the table's data, normalizedData, or displayedData.
fileName optional
A string to specify the name of the downloaded file. Defaults to "export". When fileType is xlsx, fileName must follow Excel worksheet naming guidelines.
fileType optional
A string to specify the type of the downloaded file. One of csv (default), tsv, xlsx, or json.
Return value
None.
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.
Syntax
utils.getCurrentPosition(options)
options optional
An object that contains a callback function.
| Parameter | Type | Description |
|---|---|---|
onSuccess | function | A callback function to trigger when the method runs successfully. |
Return value
An object that contains a timestamp and a coords object that contains the following properties.
| Property | Description |
|---|---|
latitude | The position’s latitude in decimal degrees. |
longitude | The position’s longitude in decimal degrees. |
speed | The velocity in meters per second. |
accuracy | The position’s accuracy in meters. |
altitude | The position’s altitude in meters above sea level. |
altitudeAccuracy | The altitude’s accuracy in meters. |
heading | The direction of travel in degrees from true north. |
Example
Retrieve the coordinates of the current user and calls updateMap upon success.
await utils.getCurrentPosition({
onSuccess: function (data) {
updateMap.trigger();
},
});
utils.getDataByObjectURL()
Converts the contents of a blob: or file:// URL to a Base64-encoded string.
Syntax
utils.getDataByObjectURL(value)
value required
A string to specify the blob or URL to convert.
Return value
A Base64-encoded string.
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.
Syntax
utils.openApp(appUuid, options)
appUuid required
A string to specify the UUID of the app to open. appUuid is in the retoolContext state while in edit mode and in the URL of the app.
options optional
An object that controls how to open the app.
| Parameter | Type | Description |
|---|---|---|
queryParams | object (optional) | An object of query parameters to pass into the app. |
newTab | boolean (optional) | Whether to open the app in a new tab. Defaults to true. |
Return value
None.
Example
Open an app with the query parameters source=updateUsersApp.
utils.openApp("371ac2f8-3aaf-11ed-8b80-836b0df4638d", {
queryParams: { source: "updateUsersApp" },
});
utils.openUrl()
Opens a URL.
Syntax
utils.openUrl(url, options)
url required
A string to specify the URL to open.
options optional
An object that controls how to open the URL.
| Parameter | Type | Description |
|---|---|---|
newTab | boolean (optional) | Whether to open the URL in a new tab. Defaults to true. |
forceReload | boolean (optional) | Whether to prevent client-side routing and force a page reload. Defaults to false. |
Return value
None.
Example
Open Retool Docs in the current tab.
utils.openUrl("https://docs.retool.com", { newTab: false });
utils.showNotification()
Shows a notification message on the top right corner of the screen.
Syntax
utils.showNotification(options)
options optional
An object that controls the notification settings.
| Parameter | Type | Description |
|---|---|---|
title | string (optional) | Title for the notification modal. Defaults to "Notification". |
description | string (optional) | Description of the notification. Defaults to an empty string. |
notificationType | string (optional) | The type of notification. One of info (default), success, warning, or error. |
duration | number (optional) | The length of time, in seconds, to display the message. Defaults to 4.5 seconds. |
Return value
None.
Example
Display a success message after deleting a user.
utils.showNotification({
title: "Deleted user",
description: "Successfully deleted user.",
notificationType: "success",
duration: 3,
});