URL parameters

A URL parameter is a piece of information you place in the browser's URL. Parameters follow a key-value pair structure and can hold many different types of data.

Parameters are useful when you want a page to carry a small piece of information that survives a reload or can be shared through a link. A common example is passing which item a user clicked to a details page: the parameter tells the page which record to display. They're also handy for navigation, since they work with the browser's back button.

Every page in your app (except the index page) has its own URL that follows a regular pattern:

Or, if you've connected a custom domain:

This points the browser to the right domain and page. That URL is really an instruction to the server: your browser sends the URL, and the server responds with the files needed to display the page.

URL parameters serve a purpose too, but instead of talking to the server, they send information to the current page. Your app can write and read parameters in the browser's URL bar and use that information in different ways.

Parameters come after the page URL, separated from it by a question mark (?). If there's more than one, each is separated by an ampersand (&).

Each parameter has a key and a value:

So the structure looks like this:

Placed in the full page URL, separated by a ?, it becomes:

To add a little more, let's rename name to firstname and add a second parameter, lastname:

From this URL, Bubble can read the full name John Doe. Here's how that works.

Reading a parameter is the other half of the round trip: once a value is in the URL, you pull it back out on the page. You tell Bubble which key to look for, and it returns that key's value.

To do this, set up an expression using the Get data from page URL data source[^2].

After picking the data source, Bubble asks for a couple of details:

As soon as you set the key, Bubble updates the expression on the right to read Get firstname from page URL.

If firstname=John exists in the URL, a text element using this expression shows John. If the parameter isn't found or has no value, it shows nothing.

The example above used the text type to read a name. Parameters can also carry other kinds of data.

Bubble's general data types (text, numbers, dates, and so on) need particular formatting to work across all browsers. Bubble applies the correct formatting automatically in most cases. If you're writing hardcoded links, or you want to understand how each type is formatted, see the box below.

You can also link to a database thing through a URL parameter. To retrieve the right thing, its unique ID needs to be in the parameter. The parameter's key doesn't affect the result, but when you use Get data from page URL, you set the type to the correct data type.

The URL would look like this:

You can also retrieve an option from an option set. Options don't have unique IDs, so they're identified by the value in their Display attribute. As with data types, you can give the parameter any key, but you set the type to the option set you want.

If the state name is stored in the Display attribute, the URL would look like this:

There are two ways to pass a parameter to a page.

Link to the page with a URL that already contains the parameters. Copying and pasting a URL with parameters into a link is enough for Bubble to recognize them on page load.

Use the Go to page action and check Send more parameters to the page. Bubble applies the necessary encoding to whatever you provide and sends the parameter.

The Go to page action lets you send parameters as a list. The left field is the key and the right field is the value. If you stay on the same page, it won't reload, but the parameters update instantly.

The Go to page action doesn't reload the page if you're going to the page you're already on. So you can set and change URL parameters as often as you need without a reload.

Some plugins can change the browser's URL, including its parameters. Bubble doesn't always catch parameter updates that aren't made with the Go to page action. Recognizing the change may need a page reload, or the plugin may be able to return the updated value itself.

A URL parameter is a piece of information that you place in the browser's URL. They follow a key-value-pair structure and can hold many different types of data.

Due to Bubble's internal logic, avoid using the following strings as keys:

Every page in your application (except for the index page) has its own URL that follows a regular pattern:

or if you have connected to a domain:

This points the browser to the right domain and to the right page. The information in that URL is actually an instruction to the server to send the correct page back to the browser. In other words, your browser sends that URL to the server, which responds by sending back the files needed to display the page.

URL parameters also serve a function, but instead of talking to the server they can send messages to the current page. In other words, your Bubble app can write and read URL parameters in the browser's URL bar and use that information for different purposes.

URL parameters are listed after the complete page URL, and are separated from that URL with a question mark (?). If there are multiple parameters, they are separated from each other with an ampersand.

Each URL parameter consists of a key and a value:

The structure would then look like this:

If we place that in the full page URL (and separate it from the URL with a ? as we explored earlier) we get:

Now to add slightly more complexity, let's change the name parameter to firstname and add a second parameter called lastname.

In this last example, Bubble would be able to identify the full name John Doe from the URL bar. Let's have a look at how that happens.

Note: There are some plugins that can manipulate the browser's URL bar, including its parameters. It's worth noting that Bubble does not always catch updates to parameters if they are not made with the Go to page action. Recognizing the change may require a page reload or the plugin may be able to return an updated value.

As we've covered, the URL parameter consists of a key and a value, and we need to instruct Bubble what key to look for in order to get the value in return.

To do that, we set up an expression where we use the Get data from page URL data source.

After picking the data source, Bubble will ask for some additional parameters:

As soon as you set the key, you can see on the right side that Bubble updates the expression to say Get firstname from page URL.

If the parameter name=John exists in the URL, the text element will show the name John to our users. If the URL parameter can't be found or has an empty value, it will display nothing.

In the example above we used the text data type to read a simple piece of information: a name. But URL parameters can also be used to read other types of data.

Bubble's general data types (text, numbers, dates, etc) need particular formatting in order to ensure compatibility with all browser.

Bubble automatically applies the correct formatting in most cases, but if you have hardcoded links or want to learn more about how the different data types are formatted, check out the info-box below.

You can also link to a custom data type in a URL parameter. To read and retrieve the correct thing, that thing's Unique ID needs to be present in the parameter. The name (key) of the parameter does not affect the result, but when you use the Get data from page URL data source you need to set it to the correct data type, as exemplified below:

The URL in this case would look like this:

You can also retrieve an option from an Option set. Option sets do not have Unique ID's but are identified by the value stored in the Display field. Just like with data types, you can give the parameter an arbitrary name, but you need to set the type to the Option set you want to retreive.

The URL in this case would look like this if we included the state name in the Display field:

There are two ways to pass URL parameters to a page:

The Go to page action lets you send the parameters by adding them in a list as illustrated above. The left-hand input field is the key and the right-hand field is the value. If you remain on the same page, the page will not be reloaded, but the parameters will be instantly updated.

You can only pass one value at a time in each URL parameter (but you can create as many parameters as you need, within the maximum URL length supported by the browser). There may be workarounds to pass lists, but it's not officially supported by Bubble at this point.

URL parameters are not insecure by and of themselves, but they can require that you understand the potential vulnerabilities associated with using them. For example: