Customize app URLs
Learn how to customize app URLs and parameters.
You can customize the URL of apps and their pages to create more discoverable links for end users. Apps also support query strings and hash properties to sync property values and control behavior.
Configure a custom URL
Retool Cloud organizations use the domain {organization}.retool.com by default. Organizations on the Business or Enterprise plan can optionally configure a custom domain.
Apps include a unique identifier in their URL by default. You can specify a custom URL path and access an app at {domain}/app/{custom-url} instead. If you're embedding the app as an IFRAME, the app can be accessed at {domain}/p/{custom-url}.
Open the Settings pane and select Page Settings. Enter a custom URL path to use for the app, then click Submit.
Configure page URLs
Each app page has a title and URL that you configure from the Inspector. The page URL is appended to the app URL and allows for deep-linking to specific pages. For example, a page with the URL of customers would be available at https://example.retool.com/app/support-dashboard/customers.
Open the Pages pane and select a page to view its settings in the Inspector. Enter a custom page URL path to use. The Inspector displays a preview of the URL to the current page.
Configure page settings.
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, short links are accessible from both your custom domain and the Retool domain.
Use URL parameters
You can use URL parameters when linking to an app and reference their values, such as passing a search term or setting the current view of a container. Retool also includes a number of built-in URL parameters to control certain characteristics of an app.
Configure custom URL parameters
You can use the url 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
- Hash properties
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.
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 app characteristics with built-in URL 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 parameters
You configure custom URL query parameters on a per-page basis. Open the Pages pane and select a page to view its settings in the Inspector. You can set each page's URL search and hash parameters which can reference any globally or page-scoped value.
When referencing dynamic values, such as {{ table.selectedRow.id }}, the URL automatically updates whenever the value changes.
Sync state between app and URL
url is page-scoped. Any URL parameters configured in one page are not accessible by another.
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
{{ url.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 }}.
