Query Parameters¶

Query parameters are key-value pairs appended to the end of a URL to pass data to the server or customize a request.

Use mo.query_params to access query parameters passed to the notebook. You can also use mo.query_params to set query parameters in order to keep track of state in the URL. This is useful for bookmarking or sharing a particular state of the notebook while running as an application with marimo run.

marimo.query_params ¶

query_params() -> QueryParams

Get the query parameters of a marimo app.

Examples:

Keep the text input in sync with the URL query parameters:

# In its own cell
query_params = mo.query_params()

# In another cell
search = mo.ui.text(
    value=query_params["search"] or "",
    on_change=lambda value: query_params.set("search", value),
)
search

You can also set the query parameters reactively:

toggle = mo.ui.switch(label="Toggle me")
toggle

# In another cell
query_params["is_enabled"] = toggle.value

RETURNS	DESCRIPTION
`QueryParams`	A QueryParams object containing the query parameters. You can directly interact with this object like a dictionary. If you mutate this object, changes will be persisted to the frontend query parameters and any other cells referencing the query parameters will automatically re-run. TYPE: `QueryParams`

Pydantic Models for Query Parameters¶

One of the use cases for URL query parameters is to set the initial state of UI elements.

Passing query parameters into a Pydantic model helps document and validate the parameters.

import marimo as mo
from pydantic import BaseModel, Field

class MyModel(BaseModel):
    r: int = Field(28, ge=0, le=255, description="Red Channel")
    g: int = Field(115, ge=0, le=255, description="Green Channel")
    b: int = Field(97, ge=0, le=255, description="Blue Channel")
    message: str = Field("<br>", description="Some text")

model = MyModel(**mo.query_params().to_dict())

# UI with initial state from query params
r_slider = mo.ui.slider(start=0, stop=255, step=1, label="R", value=model.r)
g_slider = mo.ui.slider(start=0, stop=255, step=1, label="G", value=model.g)
b_slider = mo.ui.slider(start=0, stop=255, step=1, label="B", value=model.b)

In the next cell: (see live)

bg_color = f"rgb({r_slider.value},{g_slider.value},{b_slider.value})"
mo.vstack([
    r_slider, g_slider, b_slider,
    mo.Html(model.message + bg_color).style(background_color=bg_color, text_align="center")
])

When using marimo apps mounted to FastAPI, the Pydantic model can be passed into the API documentation for the main app.

CLI arguments

You can also access command-line arguments passed to the notebook using mo.cli_args. This allows you to pass arguments to the notebook that are not controllable by the user.