fix: sync query_params on browser back/forward navigation

frontend/src/core/islands/bridge.ts

@@ -175,6 +175,16 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
     return null;
   };
 
+  sendUpdateQueryParams: RunRequests["sendUpdateQueryParams"] = async (
+    request,
+  ): Promise<null> => {
+    await this.putControlRequest({
+      type: "update-query-params",
+      ...request,
+    });
+    return null;
+  };
+
   sendFunctionRequest: RunRequests["sendFunctionRequest"] = async (
     request,
   ): Promise<null> => {

frontend/src/core/kernel/queryParamHandlers.ts

@@ -37,3 +37,24 @@ export const queryParamHandlers = {
     return;
   },
 };
+
+/**
+ * Parse URL query parameters into the format expected by the kernel.
+ */
+export function parseQueryParams(): Record<string, string | string[]> {
+  const url = new URL(window.location.href);
+  const params: Record<string, string | string[]> = {};
+
+  for (const [key, value] of url.searchParams.entries()) {
+    const existing = params[key];
+    if (existing === undefined) {
+      params[key] = value;
+    } else if (Array.isArray(existing)) {
+      existing.push(value);
+    } else {
+      params[key] = [existing, value];
+    }
+  }
+
+  return params;
+}

frontend/src/core/network/requests-network.ts

@@ -42,6 +42,14 @@ export function createNetworkRequests(): EditRequests & RunRequests {
         })
         .then(handleResponseReturnNull);
     },
+    sendUpdateQueryParams: (request) => {
+      return getClient()
+        .POST("/api/kernel/update_query_params", {
+          body: request,
+          params: getParams(),
+        })
+        .then(handleResponseReturnNull);
+    },
     sendRestart: () => {
       return getClient()
         .POST("/api/kernel/restart_session", {

frontend/src/core/network/requests-static.ts

@@ -26,6 +26,10 @@ export function createStaticRequests(): EditRequests & RunRequests {
       Logger.log("Viewing as static notebook");
       return null;
     },
+    sendUpdateQueryParams: async () => {
+      Logger.log("Query params not updated in static mode");
+      return null;
+    },
     sendFunctionRequest: async () => {
       toast({
         title: "Static notebook",

frontend/src/core/network/types.ts

@@ -93,6 +93,7 @@ export type StdinRequest = schemas["StdinRequest"];
 export type SuccessResponse = schemas["SuccessResponse"];
 export type UpdateUIElementValuesRequest =
   schemas["UpdateUIElementValuesRequest"];
+export type UpdateQueryParamsRequest = schemas["UpdateQueryParamsRequest"];
 export type UsageResponse =
   paths["/api/usage"]["get"]["responses"]["200"]["content"]["application/json"];
 export type WorkspaceFilesRequest = schemas["WorkspaceFilesRequest"];
@@ -120,6 +121,7 @@ export interface RunRequests {
   sendModelValue: (request: ModelRequest) => Promise<null>;
   sendInstantiate: (request: InstantiateNotebookRequest) => Promise<null>;
   sendFunctionRequest: (request: InvokeFunctionRequest) => Promise<null>;
+  sendUpdateQueryParams: (request: UpdateQueryParamsRequest) => Promise<null>;
 }
 
 /**

frontend/src/core/wasm/bridge.ts

@@ -416,6 +416,16 @@ export class PyodideBridge implements RunRequests, EditRequests {
     return null;
   };
 
+  sendUpdateQueryParams: RunRequests["sendUpdateQueryParams"] = async (
+    request,
+  ) => {
+    await this.putControlRequest({
+      type: "update-query-params",
+      ...request,
+    });
+    return null;
+  };
+
   sendFunctionRequest: RunRequests["sendFunctionRequest"] = async (request) => {
     await this.putControlRequest({
       type: "invoke-function",

frontend/src/core/websocket/useMarimoKernelConnection.tsx

@@ -1,7 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { useAtom, useSetAtom } from "jotai";
-import { useRef } from "react";
+import { useEffect, useRef } from "react";
 import { useErrorBoundary } from "react-error-boundary";
 import { toast } from "@/components/ui/use-toast";
 import { getNotebook, useCellActions } from "@/core/cells/cells";
@@ -51,7 +51,7 @@ import {
   handleKernelReady,
   handleRemoveUIElements,
 } from "../kernel/handlers";
-import { queryParamHandlers } from "../kernel/queryParamHandlers";
+import { queryParamHandlers, parseQueryParams } from "../kernel/queryParamHandlers";
 import type { SessionId } from "../kernel/session";
 import { kernelStateAtom } from "../kernel/state";
 import { type LayoutState, useLayoutActions } from "../layout/layout";
@@ -468,5 +468,20 @@ export function useMarimoKernelConnection(opts: {
     },
   });
 
+  // Listen for browser back/forward navigation to update query params
+  useEffect(() => {
+    const handlePopState = () => {
+      const queryParams = parseQueryParams();
+      // Import at runtime to avoid circular dependency
+      import("../network/requests").then(({ getRequestClient }) => {
+        const client = getRequestClient();
+        void client.sendUpdateQueryParams({ queryParams });
+      });
+    };
+
+    window.addEventListener("popstate", handlePopState);
+    return () => window.removeEventListener("popstate", handlePopState);
+  }, []);
+
   return { connection };
 }

marimo/_runtime/commands.py

@@ -449,6 +449,19 @@ def ids_and_values(self) -> list[tuple[UIElementId, Any]]:
         return list(zip(self.object_ids, self.values, strict=False))
 
 
+class UpdateQueryParamsCommand(Command):
+    """Update query parameters from browser navigation.
+
+    Triggered when user navigates using browser back/forward buttons.
+    Updates query params state and re-executes dependent cells.
+
+    Attributes:
+        query_params: New query parameter values from URL.
+    """
+
+    query_params: SerializedQueryParams
+
+
 class InvokeFunctionCommand(Command):
     """Invoke a function from a UI element.
 
@@ -896,6 +909,7 @@ class GetCacheInfoCommand(Command):
     | InstallPackagesCommand
     # UI element and widget model operations
     | UpdateUIElementCommand
+    | UpdateQueryParamsCommand
     | ModelCommand
     | InvokeFunctionCommand
     # User/configuration operations

marimo/_runtime/runtime.py

@@ -150,6 +150,7 @@
     StorageListEntriesCommand,
     SyncGraphCommand,
     UpdateCellConfigCommand,
+    UpdateQueryParamsCommand,
     UpdateUIElementCommand,
     UpdateUserConfigCommand,
     ValidateSQLCommand,
@@ -2432,6 +2433,19 @@ async def handle_function_call(request: InvokeFunctionCommand) -> None:
                 ),
             )
 
+        async def handle_update_query_params(
+            request: UpdateQueryParamsCommand,
+        ) -> None:
+            # Update the kernel's query_params state
+            self.query_params._params.clear()
+            self.query_params._params.update(request.query_params)
+            # Trigger state update to re-run dependent cells
+            self.query_params._set_value(self.query_params._params)
+            # Process the state updates
+            if self.state_updates:
+                await self._run_cells(set())
+            broadcast_notification(CompletedRunNotification())
+
         async def handle_set_user_config(
             request: UpdateUserConfigCommand,
         ) -> None:
@@ -2461,6 +2475,7 @@ async def handle_stop(request: StopKernelCommand) -> None:
         handler.register(RenameNotebookCommand, handle_rename)
         handler.register(UpdateCellConfigCommand, self.set_cell_config)
         handler.register(UpdateUIElementCommand, handle_set_ui_element_value)
+        handler.register(UpdateQueryParamsCommand, handle_update_query_params)
         handler.register(ModelCommand, handle_receive_model_message)
         handler.register(UpdateUserConfigCommand, handle_set_user_config)
         handler.register(StopKernelCommand, handle_stop)

marimo/_server/api/endpoints/execution.py

@@ -115,6 +115,36 @@ async def set_model_values(
     return await dispatch_control_request(request, ModelRequest)
 
 
+@router.post("/update_query_params")
+@requires("read")
+async def update_query_params(
+    *,
+    request: Request,
+) -> BaseResponse:
+    """
+    parameters:
+        - in: header
+          name: Marimo-Session-Id
+          schema:
+            type: string
+          required: true
+    requestBody:
+        content:
+            application/json:
+                schema:
+                    $ref: "#/components/schemas/UpdateQueryParamsRequest"
+    responses:
+        200:
+            description: Update query parameters from browser navigation
+            content:
+                application/json:
+                    schema:
+                        $ref: "#/components/schemas/SuccessResponse"
+    """
+    from marimo._server.models.models import UpdateQueryParamsRequest
+    return await dispatch_control_request(request, UpdateQueryParamsRequest)
+
+
 @router.post("/instantiate")
 @requires("edit")
 async def instantiate(

marimo/_server/models/models.py

@@ -25,9 +25,11 @@
     ModelCommand,
     PreviewDatasetColumnCommand,
     PreviewSQLTableCommand,
+    SerializedQueryParams,
     StorageDownloadCommand,
     StorageListEntriesCommand,
     UpdateCellConfigCommand,
+    UpdateQueryParamsCommand,
     UpdateUIElementCommand,
     UpdateUserConfigCommand,
     ValidateSQLCommand,
@@ -80,6 +82,13 @@ def as_command(self) -> UpdateUIElementCommand:
         )
 
 
+class UpdateQueryParamsRequest(UpdateQueryParamsCommand, tag=False):
+    def as_command(self) -> UpdateQueryParamsCommand:
+        return UpdateQueryParamsCommand(
+            query_params=self.query_params,
+        )
+
+
 class ModelRequest(ModelCommand, tag=False):
     def as_command(self) -> ModelCommand:
         return ModelCommand(