URL query parameters

Retool's built-in URL query parameters allow you to control certain characteristics of an app when launched. You can also configure your own URL query parameters and deep link to specific sections or data.

Built-in URL query parameters

You can launch an app and include any of the following parameters in its URL, allowing you to control the app's state when launched. For example, use URL parameters to load a previous release or use specific environments. Use the following URL format when including query parameters:

https://[organization].retool.com/apps/[app]?[parameter]=[value]

Parameter	Value	Description
`_historyOffset`	Any integer (`1`, `2`, `3`, etc.)	Opens the Retool app to a previous point in its save history, counting back from the latest state. This is useful if you need to roll back changes because an app is not in a functional state (e.g., an infinite loop). If you edit an app while in an offset version, those changes are saved at the "newest" position in the app history. We recommend using releases as you make changes to apps.
`_embed`	`true` or `false`	Hides all non-app UI. Useful for embedding Retool into other applications.
`_releaseVersion`	Any valid release number (e.g, `2.1.1`) or `latest`	Opens the Retool app to a specific release version. Helpful for testing or sharing new changes with teammates.
`_environment`	Any valid environment name (e.g., `production` or `staging`)	Opens the Retool app with the corresponding environment credentials. This is the same as clicking the environments dropdown via the UI.
`_hideNav`	`true` or `false`	Hides the Retool navigation bar.
`_hideTimer`	`true` or `false`	Hides the query timer.

📘
You can also define custom query parameters to use in queries and link directly to records.

Custom URL query parameters

You can specify your own URL query parameters to include custom values, allowing you to effectively sync its state to the URL. This makes it possible to link directly to specific records.

The following example shows an app that allows you to search for users and their purchases. You can use URL parameters to share a link to the app with a specific user already populated.

Users and purchases tables

To use deep links:

Open the ... menu and click on URL parameters to open the URL parameters menu.

URL parameters highlighted in file menu

To automatically update the URL whenever a user searches for a value, selects a user, or selects a purchase, configure the parameters:

Storing page state in the URL.

Now the page has a URL that looks like this: https://yourdomain.tryretool.com/presentation/UsersDashboard#customerId=45&purchaseId=1979&searchTerm=ja

One-way syncing now works, but page state should also update based on the URL. Opening the app with URL parameters should set the search box and the selected rows in the tables. To do that, fill in the second half:

Reading page state from the URL.

If you're setting default values, update them to read from your URL query parameters.

For example, set the default table index to read from the customerId URL parameter.

Update default index to read from URL parameter

Now, when you open up the URL https://yourdomain.tryretool.com/presentation/UsersDashboard#customerId=45&purchaseId=1979&searchTerm=ja, you'll see the correct selected customer and purchase.