How to Use url_key in Mercury Widgets

The url_key argument lets you initialize widget values directly from URL query parameters.

This is useful when you want to:

• prefill widgets from a shared link,
• create bookmarkable app states,
• link dashboards with predefined filters,
• pass parameters from another app into a Mercury notebook.

What url_key does

When a widget supports url_key, Mercury reads the corresponding query parameter from the page URL during initialization and uses it to override the widget’s default value.

In practice, this means that code like this:

import mercury as mr

country = mr.Select(
    label="Country",
    choices=["Poland", "Germany", "France"],
    value="Poland",
    url_key="country"
)

can be initialized from a URL such as:

http://localhost:8888/mercury/example_notebook?country=Germany

In that case, the widget starts with "Germany" instead of "Poland".

Note

url_key affects the initial widget value during app startup. It does not continuously sync the widget with later URL changes.

Widgets that support url_key

The following Mercury widgets support url_key:

• TextInput
• NumberInput
• Slider
• Select
• MultiSelect
• CheckBox

Validation rules by widget

Each widget validates URL values differently before accepting them.

TextInput

• reads the first value for the given url_key
• accepts non-empty text values
• uses the widget value if the URL value is invalid

NumberInput

• reads the first value for the given url_key
• accepts numeric values
• clamps values to the valid range and nearest step
• uses the widget value if the URL value is invalid

Slider

• reads the first value for the given url_key
• accepts numeric values
• clamps values to the valid range
• uses the widget value if the URL value is invalid

Select

• reads the first value for the given url_key
• accepts non-empty values that match one of choices
• uses the widget value if the URL value is invalid

MultiSelect

• reads all values for the given url_key
• accepts non-empty values that match one of choices
• uses the widget value if the URL value is invalid

CheckBox

• reads the first value for the given url_key
• accepts only true or false
• uses the widget value if the URL value is invalid

Examples

TextInput

Code

import mercury as mr

username = mr.TextInput(
    label="User name",
    value="guest",
    url_key="username"
)

username.value

Example URL

http://localhost:8888/mercury/example_notebook?username=jan

Result

---

NumberInput

Code

import mercury as mr

rows = mr.NumberInput(
    label="Rows",
    value=10,
    min=0,
    max=100,
    step=5,
    url_key="rows"
)

rows.value

Example URL

http://localhost:8888/mercury/example_notebook?rows=18

Result

The value is 20 because with step=5, 20 is the closest valid value to 18.

---

Slider

Code

import mercury as mr

age = mr.Slider(
    label="Age",
    value=25,
    min=0,
    max=100,
    url_key="age"
)

age.value

Example URL

http://localhost:8888/mercury/example_notebook?age=42

Result

---

Select

Code

import mercury as mr

country = mr.Select(
    label="Country",
    choices=["Poland", "Germany", "France"],
    value="Poland",
    url_key="country"
)

country.value

Example URL

http://localhost:8888/mercury/example_notebook?country=Germany

Result

---

MultiSelect

Code

import mercury as mr

fruits = mr.MultiSelect(
    label="Fruits",
    choices=["Apple", "Banana", "Orange", "Kiwi"],
    value=["Apple"],
    url_key="fruit"
)

fruits.value

Example URL

http://localhost:8888/mercury/example_notebook?fruit=Banana&fruit=Orange

Result

The widget starts with:

---

CheckBox

Code

import mercury as mr

show_details = mr.CheckBox(
    label="Show details",
    value=False,
    url_key="details"
)

show_details.value

Example URL

http://localhost:8888/mercury/example_notebook?details=true

Result

Tip

Use descriptive keys that explain what the value represents.

• Good examples: country, rows, show_details, fruit
• Avoid generic names like x, v, or param1.

What happens if multiple widgets use the same url_key?

Multiple widgets can use the same url_key, but each widget interprets the URL value using its own validation rules.

That means the same URL parameter may be accepted by some widgets and ignored by others.

Example

Code

import mercury as mr

text_username = mr.TextInput(
    label="Text username",
    value="guest",
    url_key="user"
)

select_username = mr.Select(
    label="Select username",
    choices=["guest", "admin", "editor"],
    value="guest",
    url_key="user"
)

number_username = mr.NumberInput(
    label="Numeric user id",
    value=1,
    min=1,
    max=100,
    url_key="user"
)

Example URL

http://localhost:8888/mercury/example_notebook?user=admin

Result

What happens

• TextInput becomes "admin"
• Select becomes "admin" because it is present in choices
• NumberInput ignores "admin" (nonnumeric value) and keeps its fallback value

Note

Sharing the same url_key between multiple widgets is supported, but it is usually clearer to use separate keys unless you intentionally want several widgets to derive state from the same URL parameter.

Summary

url_key makes it possible to initialize Mercury widgets from URL query parameters, enabling shareable links, bookmarkable state, and URL-driven defaults.

Choose a clear url_key, provide a sensible fallback value, and test the exact URL formats your app should support.