Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat: support theme override via query param (#10196)

Kiran Gadhavea1b5ea23e8d7
diff --git a/frontend/src/core/constants.ts b/frontend/src/core/constants.ts
index 42167d1dfa..4276ed7033 100644
--- a/frontend/src/core/constants.ts
+++ b/frontend/src/core/constants.ts
@@ -50,6 +50,12 @@ export const KnownQueryParams = {
* If false, the chrome will be hidden.
*/
showChrome: "show-chrome",
+ /**
+ * Override the display theme: `light`, `dark`, or `system`.
+ * Takes precedence over the notebook's saved `display.theme`.
+ * Ignored for embedded islands, which infer the theme from their host page.
+ */
+ theme: "theme",
};
/**
diff --git a/frontend/src/theme/__tests__/useTheme.test.ts b/frontend/src/theme/__tests__/useTheme.test.ts
new file mode 100644
index 0000000000..91c8be73dd
--- /dev/null
+++ b/frontend/src/theme/__tests__/useTheme.test.ts
@@ -0,0 +1,68 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { afterEach, describe, expect, it } from "vitest";
+import { configOverridesAtom, userConfigAtom } from "@/core/config/config";
+import { defaultUserConfig } from "@/core/config/config-schema";
+import { store } from "@/core/state/jotai";
+import type { Theme } from "../useTheme";
+import { resolvedThemeAtom, visibleForTesting } from "../useTheme";
+
+const { themeFromQueryParam } = visibleForTesting;
+
+function setQuery(search: string): void {
+ window.history.replaceState({}, "", search === "" ? "/" : `/?${search}`);
+}
+
+function setConfigTheme(theme: Theme): void {
+ const config = defaultUserConfig();
+ store.set(userConfigAtom, {
+ ...config,
+ display: { ...config.display, theme },
+ });
+}
+
+afterEach(() => {
+ setQuery("");
+ store.set(userConfigAtom, defaultUserConfig());
+ store.set(configOverridesAtom, {});
+});
+
+describe("themeFromQueryParam", () => {
+ it.each(["light", "dark", "system"] as const)(
+ "returns the valid theme %s",
+ (theme) => {
+ setQuery(`theme=${theme}`);
+ expect(themeFromQueryParam()).toBe(theme);
+ },
+ );
+
+ it("returns undefined when the param is absent", () => {
+ setQuery("");
+ expect(themeFromQueryParam()).toBeUndefined();
+ });
+
+ it("returns undefined for an invalid value", () => {
+ setQuery("theme=blue");
+ expect(themeFromQueryParam()).toBeUndefined();
+ });
+});
+
+describe("resolvedThemeAtom with a theme query param", () => {
+ it("uses the saved config theme when no param is present", () => {
+ setConfigTheme("dark");
+ setQuery("");
+ expect(store.get(resolvedThemeAtom)).toBe("dark");
+ });
+
+ it("lets the query param override the saved config theme", () => {
+ setConfigTheme("light");
+ setQuery("theme=dark");
+ expect(store.get(resolvedThemeAtom)).toBe("dark");
+ });
+
+ it("falls back to the config theme for an invalid param value", () => {
+ setConfigTheme("dark");
+ setQuery("theme=blue");
+ expect(store.get(resolvedThemeAtom)).toBe("dark");
+ });
+});
diff --git a/frontend/src/theme/useTheme.ts b/frontend/src/theme/useTheme.ts
index b9816ff8a6..f73c663a13 100644
--- a/frontend/src/theme/useTheme.ts
+++ b/frontend/src/theme/useTheme.ts
@@ -2,6 +2,7 @@
import { atom, useAtomValue } from "jotai";
import { resolvedMarimoConfigAtom } from "@/core/config/config";
+import { KnownQueryParams } from "@/core/constants";
import { isIslands } from "@/core/islands/utils";
import { store } from "@/core/state/jotai";
@@ -10,6 +11,16 @@ export type ResolvedTheme = "light" | "dark";
export const THEMES: Theme[] = ["light", "dark", "system"];
+function themeFromQueryParam(): Theme | undefined {
+ if (typeof window === "undefined") {
+ return undefined;
+ }
+ const value = new URLSearchParams(window.location.search).get(
+ KnownQueryParams.theme,
+ );
+ return THEMES.includes(value as Theme) ? (value as Theme) : undefined;
+}
+
const themeAtom = atom((get) => {
// If it is islands, try a few ways to infer if it is dark mode.
if (isIslands()) {
@@ -51,7 +62,7 @@ const themeAtom = atom((get) => {
return "light";
}
- return get(resolvedMarimoConfigAtom).display.theme;
+ return themeFromQueryParam() ?? get(resolvedMarimoConfigAtom).display.theme;
});
const prefersDarkModeAtom = atom(false);
@@ -122,3 +133,7 @@ export function useTheme(): { theme: ResolvedTheme } {
const theme = useAtomValue(resolvedThemeAtom, { store });
return { theme };
}
+
+export const visibleForTesting = {
+ themeFromQueryParam,
+};