Skip to main content

Configure URL parameters

Learn how to control app behavior and pass values using URL parameters.

Version: Cloud and 3.178 Edge

You can include URL query strings and hash parameters when linking to an app page 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 URL parameters​

You can include any hash or query string parameters within an app's URL. URL parameters are page-scoped and only accessible from the page specified in the URL. If no page is specified, URL parameters are available within the app's default page.

You can configure page-specific URL parameters that reference values and update the URL whenever they change. This allows users to link to an app's current state, such as a selected table row, or sync values between different pages and apps.

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 to reference any globally or page-scoped value. Any changes to referenced values are then automatically reflected in the current URL and in the url object.

Search query parameters​

You can provide search query parameters by appending ? to the URL and using the format key=value. Use the & symbol as a separator to provide multiple key-value pairs.

https://example.retool.com/app/users?role=viewer&team=workplace&q=chic

Hash parameters​

You can also provide hash parameters by appending # to the URL using the format key=value. Use the & symbol as a separator to provide multiple key-value pairs.

https://example.retool.com/app/users#enabled=true

If you need to include both types of parameters, hash parameters must be after query strings.

https://example.retool.com/app/customer-dashboard?q=chic&role=viewer&team=workplace#enabled=true

Reference URL parameters​

You can use URL parameters in the app by referencing the url object.

url​

object
Properties

hashParams​

object

An array of URL hash parameters in the current URL.

searchParams​

object

An array of URL query string parameters in the current URL.

href​

string

The complete URL with parameters and hash fragments.

Both hashParams and searchParams contain key-value pairs that represent their respective parameters within the current URL.

{
  "hashParams": {
    "enabled": true
  },
  "searchParams: {
    "role": "viewer",
    "q": "chic",
    "team": "workplace"
  }
}

For example, you would reference these parameters using {{ url.hashParams.enabled }} and {{ url.searchParams.q }}. You can use these almost anywhere within the app, such as populating an input component or query parameter.

Demo

You can also include URL query parameters when configuring the Open page or Open app event handlers.

Configure URL parameters when linking to other pages or apps.

Persist URL parameters​

You can chose whether all "Go to page" event handers should have the Persist URL Params setting enabled by default. When enabled, search query parameters and hash parameters persist during page navigation and when switching pages with the “Go to Page” event handlers.

Turn on this setting by navigating to the App Inspector, and enable Persist URL Parameters.

If enabling this setting would override a specific “Go to Page” handler’s settings, a confirmation popup appears, asking the user to confirm the override.