tools-only Query Parameters API Reference
Access and manipulate URL query parameters in marimo apps.
Overview
Query parameters allow:
- Passing data through URLs
- Persisting UI state in the URL
- Sharing specific app states via links
- Deep linking to filtered views
Basic Usage
mo.query_params
Get the query parameters object.
import marimo as mo
# Get query params (dict-like object)
params = mo.query_params()
# Read parameter
search = params.get("search", "")
page = params.get("page", "1")
# Check if parameter exists
if "filter" in params:
apply_filter(params["filter"])
Reading Parameters
params = mo.query_params()
# Get with default
value = params.get("key", "default")
# Direct access (may raise KeyError)
value = params["key"]
# Get all as dict
all_params = params.to_dict()
# Iterate
for key, value in params.items():
print(f"{key}: {value}")
Setting Parameters
params = mo.query_params()
# Set single parameter
params["search"] = "hello"
# Set using method
params.set("page", "2")
# Set multiple
params.update({
"search": "hello",
"page": "1",
"sort": "date"
})
# Remove parameter
del params["filter"]
params.pop("filter", None)
# Clear all
params.clear()
Syncing UI with URL
Text Input
params = mo.query_params()
search = mo.ui.text(
value=params.get("search", ""),
placeholder="Search...",
v: params.set("search", v)
)
Dropdown
params = mo.query_params()
sort_options = ["date", "name", "size"]
sort = mo.ui.dropdown(
options=sort_options,
value=params.get("sort", "date"),
v: params.set("sort", v)
)
Checkbox
params = mo.query_params()
# Boolean as string
show_all = mo.ui.checkbox(
label="Show all",
value=params.get("show_all") == "true",
v: params.set("show_all", "true" if v else "false")
)
Slider
params = mo.query_params()
threshold = mo.ui.slider(
0, 100,
value=int(params.get("threshold", "50")),
v: params.set("threshold", str(v))
)
Reactive Updates
Query params integrate with marimo's reactivity:
# Cell 1
params = mo.query_params()
# Cell 2 - reacts to URL changes
search_term = params.get("search", "")
results = search_database(search_term)
# Cell 3 - display results
mo.ui.table(results)
Validation with Pydantic
Use Pydantic for type-safe query parameters:
from pydantic import BaseModel, Field
class FilterParams(BaseModel):
search: str = ""
page: int = Field(1, ge=1)
per_page: int = Field(10, ge=1, le=100)
sort: str = Field("date", pattern="^(date|name|size)$")
# Parse and validate
params = mo.query_params()
try:
filters = FilterParams(**params.to_dict())
except ValidationError as e:
mo.callout(f"Invalid parameters: {e}", kind="danger")
URL Patterns
Building Shareable URLs
# Set parameters for sharing
params = mo.query_params()
params.update({
"view": "chart",
"date_range": "2024-01-01,2024-12-31",
"categories": "a,b,c"
})
# URL becomes: ?view=chart&date_range=2024-01-01,2024-12-31&categories=a,b,c
Parsing Complex Values
params = mo.query_params()
# Parse comma-separated list
categories = params.get("categories", "").split(",") if params.get("categories") else []
# Parse date range
date_range = params.get("date_range", "")
if date_range:
start, end = date_range.split(",")
Complete Example
# Cell 1: Query params
params = mo.query_params()
# Cell 2: UI controls synced with URL
search = mo.ui.text(
value=params.get("q", ""),
placeholder="Search...",
v: params.set("q", v)
)
category = mo.ui.dropdown(
["All", "Electronics", "Books", "Clothing"],
value=params.get("cat", "All"),
v: params.set("cat", v)
)
sort_by = mo.ui.radio(
["Relevance", "Price", "Rating"],
value=params.get("sort", "Relevance"),
v: params.set("sort", v)
)
mo.vstack([search, category, sort_by])
# Cell 3: Filtered results
results = filter_products(
query=search.value,
category=None if category.value == "All" else category.value,
sort=sort_by.value.lower()
)
mo.ui.table(results)
Best Practices
Use Meaningful Parameter Names
# Good
params.set("search_query", value)
params.set("date_start", "2024-01-01")
# Less clear
params.set("q", value)
params.set("ds", "2024-01-01")
Handle Missing Parameters
# Always provide defaults
page = int(params.get("page", "1"))
search = params.get("search", "")
Validate Before Using
page = params.get("page", "1")
try:
page_num = int(page)
if page_num < 1:
page_num = 1
except ValueError:
page_num = 1
Keep URLs Clean
# Remove empty parameters
if not search.value:
params.pop("search", None)
else:
params.set("search", search.value)
Limitations
- Query params are strings; convert types manually
- Long URLs may hit browser limits
- Not suitable for sensitive data
- Changes trigger cell re-execution