Configure URL query parameters

You can include URL query parameters when linking to an app and reference their values, such as passing a search term or setting the current view of a container. You can configure custom URL query parameters to store values in the URL and launch apps with certain characteristics using Retool's built-in URL query parameters.

Launch an app with URL query parameters

Retool supports query strings and [hash properties] when linking to an app. You can include these without any additional configuration to pass values into an app.

You can use the urlParams object to reference query strings, hash properties, and the current href value within apps. For example, you can set the Default view of a Container component with multiple views with {{ urlParams.view }}. Including the query string view=users would automatically select the users view key.

You can also include URL query parameters when configuring the Open app event handler.

Query strings

Query strings are key-value pairs appended to the app URL after the ? separator. You can include multiple query strings using the & separator, such as foo=bar&retool=awesome&hello=world.

Hash properties

A hash property contains key-value pairs appended to the URL after the # separator. Only one hash property can be included in a URL but it can contain multiple key-value pairs using the & separator.

Control characteristics with built-in URL query parameters

🚧
Public apps do not support built-in query parameters.

You can include the following query strings to control certain characteristics on launch, such as loading a specific release or environment.

Query string	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.

Configure custom URL query parameters

You configure custom URL query parameters in the URL parameters settings to sync property values as hash properties in the URL. Once configured, any changes to these values update automatically and also updates the current app state.

Store property values to the URL

To store property values in the URL, specify the parameter key names and corresponding values to store in the URL. Once set, any changes to those values automatically update the URL in the browser.

Storing page state in the URL.

Retrieve property values from the URL

To retrieve property values from the URL and update app state, specify which component properties to connect and a corresponding value.

Sync state between app and URL

To sync between the app and its URL, ensure that you both store the property value in the URL and connect the same property to the URL value. For example:

Store a search term using the searchTerm key with a value of {{ userSearch.value }}, a Text Input component.
Connect userSearch.value to {{ urlParams.hash.searchTerm }}.

Once configured, value changes are continually reflected between the app and URL. The following demo includes the query parameter #searchTerm=claire.