Customize app URLs
Learn how to create and share custom app URLs and configure URL query parameters and hash properties.
Add custom URLs to your app
You can create a custom URL for your app to make it more discoverable by your end users. With a custom URL set, your app can be accessed at {domain}/app/{custom-url}. When sharing a Public Link, the app can be accessed at {domain}/p/{custom-url}.
Create and share a custom URL
Below is a walkthrough for creating a custom URL for your Retool app.
Disabling a custom URL makes all prior references invalid. You can disable a custom URL in App Settings > Page Settings.
Accessing apps with a custom URL
Apps with custom URLs always display the custom URL in the browser's address bar unless you're editing the app or using the mobile view. Even if you access the app from another app, publicly, or from the original link, the custom URL is displayed.
If you have a custom domain, shortlinks are accessible from both your custom domain and the Retool domain.
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. Retool recommends 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.
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
searchTermkey 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.
To set a default value on a component when connecting properties between the app and URL, use the URL parameter settings rather than the component's default value.
For example, to set the userSearch Text Input component to default to "Engineering", use a conditional when setting {{ userSearch.value }}.
