You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by jl...@apache.org on 2026/06/08 16:28:16 UTC

(superset) branch master updated: feat(embedded): support themeMode URL param for initial theme (#40760)

This is an automated email from the ASF dual-hosted git repository.

sadpandajoe pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git


The following commit(s) were added to refs/heads/master by this push:
     new dc423b22b31 feat(embedded): support themeMode URL param for initial theme (#40760)
dc423b22b31 is described below

commit dc423b22b316dff90169f88cf8c778cf9c5e3b15
Author: Onur Taşhan <on...@gmail.com>
AuthorDate: Mon Jun 8 19:28:09 2026 +0300

    feat(embedded): support themeMode URL param for initial theme (#40760)
    
    Co-authored-by: Claude Sonnet 4.6 <no...@anthropic.com>
---
 superset-embedded-sdk/README.md                    | 116 +++++++++++++--------
 .../src/embedded/EmbeddedContextProviders.tsx      |   5 +-
 .../src/embedded/getInitialThemeMode.test.ts       |  66 ++++++++++++
 .../src/embedded/getInitialThemeMode.ts            |  35 +++++++
 4 files changed, 179 insertions(+), 43 deletions(-)

diff --git a/superset-embedded-sdk/README.md b/superset-embedded-sdk/README.md
index 6184aebffc8..2b3058652be 100644
--- a/superset-embedded-sdk/README.md
+++ b/superset-embedded-sdk/README.md
@@ -29,8 +29,8 @@ Embedding is done by inserting an iframe, containing a Superset page, into the h
 
 ## Prerequisites
 
-* Activate the feature flag `EMBEDDED_SUPERSET`
-* Set a strong password in configuration variable `GUEST_TOKEN_JWT_SECRET` (see configuration file config.py). Be aware that its default value must be changed in production.
+- Activate the feature flag `EMBEDDED_SUPERSET`
+- Set a strong password in configuration variable `GUEST_TOKEN_JWT_SECRET` (see configuration file config.py). Be aware that its default value must be changed in production.
 
 ## Embedding a Dashboard
 
@@ -41,32 +41,37 @@ npm install --save @superset-ui/embedded-sdk
 ```
 
 ```js
-import { embedDashboard } from "@superset-ui/embedded-sdk";
+import { embedDashboard } from '@superset-ui/embedded-sdk';
 
 embedDashboard({
-  id: "abc123", // given by the Superset embedding UI
-  supersetDomain: "https://superset.example.com",
-  mountPoint: document.getElementById("my-superset-container"), // any html element that can contain an iframe
+  id: 'abc123', // given by the Superset embedding UI
+  supersetDomain: 'https://superset.example.com',
+  mountPoint: document.getElementById('my-superset-container'), // any html element that can contain an iframe
   fetchGuestToken: () => fetchGuestTokenFromBackend(),
-  dashboardUiConfig: { // dashboard UI config: hideTitle, hideTab, hideChartControls, filters.visible, filters.expanded (optional), urlParams (optional)
-      hideTitle: true,
-      filters: {
-          expanded: true,
-      },
-      urlParams: {
-          foo: 'value1',
-          bar: 'value2',
-          // ...
-      }
+  dashboardUiConfig: {
+    // dashboard UI config: hideTitle, hideTab, hideChartControls, filters.visible, filters.expanded (optional), urlParams (optional)
+    hideTitle: true,
+    filters: {
+      expanded: true,
+    },
+    urlParams: {
+      foo: 'value1',
+      bar: 'value2',
+      // themeMode: 'dark', // set the initial theme: 'dark' | 'system' | 'default' (default: 'default')
+      // ...
+    },
   },
   // optional additional iframe sandbox attributes
-  iframeSandboxExtras: ['allow-top-navigation', 'allow-popups-to-escape-sandbox'],
+  iframeSandboxExtras: [
+    'allow-top-navigation',
+    'allow-popups-to-escape-sandbox',
+  ],
   // optional Permissions Policy features
   iframeAllowExtras: ['clipboard-write', 'fullscreen'],
   // optional config to enforce a particular referrerPolicy
-  referrerPolicy: "same-origin",
+  referrerPolicy: 'same-origin',
   // optional callback to customize permalink URLs
-  resolvePermalinkUrl: ({ key }) => `https://my-app.com/analytics/share/${key}`
+  resolvePermalinkUrl: ({ key }) => `https://my-app.com/analytics/share/${key}`,
 });
 ```
 
@@ -97,7 +102,7 @@ Guest tokens can have Row Level Security rules which filter data for the user ca
 
 The agent making the `POST` request must be authenticated with the `can_grant_guest_token` permission.
 
-Within your app, using the Guest Token will then allow authentication to your Superset instance via creating an Anonymous user object.  This guest anonymous user will default to the public role as per this setting `GUEST_ROLE_NAME = "Public"`.
+Within your app, using the Guest Token will then allow authentication to your Superset instance via creating an Anonymous user object. This guest anonymous user will default to the public role as per this setting `GUEST_ROLE_NAME = "Public"`.
 
 The user parameters in the example below are optional and are provided as a means of passing user attributes that may be accessed in jinja templates inside your charts.
 
@@ -110,13 +115,13 @@ Example `POST /security/guest_token` payload:
     "first_name": "Stan",
     "last_name": "Lee"
   },
-  "resources": [{
-    "type": "dashboard",
-    "id": "abc123"
-  }],
-  "rls": [
-    { "clause": "publisher = 'Nintendo'" }
-  ]
+  "resources": [
+    {
+      "type": "dashboard",
+      "id": "abc123"
+    }
+  ],
+  "rls": [{ "clause": "publisher = 'Nintendo'" }]
 }
 ```
 
@@ -152,15 +157,43 @@ In this example, the configuration file includes the following setting:
 GUEST_TOKEN_JWT_AUDIENCE="superset"
 ```
 
+### Setting the Initial Theme Mode
+
+Use the `themeMode` URL parameter to control the embedded dashboard's initial colour scheme:
+
+```js
+embedDashboard({
+  id: 'abc123',
+  supersetDomain: 'https://superset.example.com',
+  mountPoint: document.getElementById('my-superset-container'),
+  fetchGuestToken: () => fetchGuestTokenFromBackend(),
+  dashboardUiConfig: {
+    urlParams: {
+      themeMode: 'dark', // 'dark' | 'system' | 'default' (default: 'default')
+    },
+  },
+});
+```
+
+The supported values are:
+
+| Value     | Behaviour                                                 |
+| --------- | --------------------------------------------------------- |
+| `default` | Light theme (Superset default)                            |
+| `dark`    | Dark theme                                                |
+| `system`  | Follows the user's OS preference (`prefers-color-scheme`) |
+
+The theme can also be changed at runtime via `embeddedDashboard.setThemeMode(mode)`.
 
 ### Sandbox iframe
 
 The Embedded SDK creates an iframe with [sandbox](https://developer.mozilla.org/es/docs/Web/HTML/Element/iframe#sandbox) mode by default
 which applies certain restrictions to the iframe's content.
 To pass additional sandbox attributes you can use `iframeSandboxExtras`:
+
 ```js
-  // optional additional iframe sandbox attributes
-  iframeSandboxExtras: ['allow-top-navigation', 'allow-popups-to-escape-sandbox']
+// optional additional iframe sandbox attributes
+iframeSandboxExtras: ['allow-top-navigation', 'allow-popups-to-escape-sandbox'];
 ```
 
 ### Permissions Policy
@@ -168,11 +201,12 @@ To pass additional sandbox attributes you can use `iframeSandboxExtras`:
 To enable specific browser features within the embedded iframe, use `iframeAllowExtras` to set the iframe's [Permissions Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy) (the `allow` attribute):
 
 ```js
-  // optional Permissions Policy features
-  iframeAllowExtras: ['clipboard-write', 'fullscreen']
+// optional Permissions Policy features
+iframeAllowExtras: ['clipboard-write', 'fullscreen'];
 ```
 
 Common permissions you might need:
+
 - `clipboard-write` - Required for "Copy permalink to clipboard" functionality
 - `fullscreen` - Required for fullscreen chart viewing
 - `camera`, `microphone` - If your dashboards include media capture features
@@ -191,16 +225,16 @@ When users click share buttons inside an embedded dashboard, Superset generates
 
 ```js
 embedDashboard({
-  id: "abc123",
-  supersetDomain: "https://superset.example.com",
-  mountPoint: document.getElementById("my-superset-container"),
+  id: 'abc123',
+  supersetDomain: 'https://superset.example.com',
+  mountPoint: document.getElementById('my-superset-container'),
   fetchGuestToken: () => fetchGuestTokenFromBackend(),
 
   // Customize permalink URLs
   resolvePermalinkUrl: ({ key }) => {
     // key: the permalink key (e.g., "xyz789")
     return `https://my-app.com/analytics/share/${key}`;
-  }
+  },
 });
 ```
 
@@ -211,15 +245,15 @@ To restore the dashboard state from a permalink in your app:
 const permalinkKey = routeParams.key;
 
 embedDashboard({
-  id: "abc123",
-  supersetDomain: "https://superset.example.com",
-  mountPoint: document.getElementById("my-superset-container"),
+  id: 'abc123',
+  supersetDomain: 'https://superset.example.com',
+  mountPoint: document.getElementById('my-superset-container'),
   fetchGuestToken: () => fetchGuestTokenFromBackend(),
   resolvePermalinkUrl: ({ key }) => `https://my-app.com/analytics/share/${key}`,
   dashboardUiConfig: {
     urlParams: {
-      permalink_key: permalinkKey,  // Restores filters, tabs, chart states, and scrolls to anchor
-    }
-  }
+      permalink_key: permalinkKey, // Restores filters, tabs, chart states, and scrolls to anchor
+    },
+  },
 });
 ```
diff --git a/superset-frontend/src/embedded/EmbeddedContextProviders.tsx b/superset-frontend/src/embedded/EmbeddedContextProviders.tsx
index 3846f697d11..ba239e9f52f 100644
--- a/superset-frontend/src/embedded/EmbeddedContextProviders.tsx
+++ b/superset-frontend/src/embedded/EmbeddedContextProviders.tsx
@@ -26,9 +26,10 @@ import { DynamicPluginProvider } from 'src/components';
 import { EmbeddedUiConfigProvider } from 'src/components/UiConfigContext';
 import { SupersetThemeProvider } from 'src/theme/ThemeProvider';
 import { ThemeController } from 'src/theme/ThemeController';
-import { type ThemeStorage, ThemeMode } from '@apache-superset/core/theme';
+import { type ThemeStorage } from '@apache-superset/core/theme';
 import { store } from 'src/views/store';
 import querystring from 'query-string';
+import { getInitialThemeMode } from './getInitialThemeMode';
 
 /**
  * In-memory implementation of ThemeStorage interface for embedded contexts.
@@ -52,7 +53,7 @@ class ThemeMemoryStorageAdapter implements ThemeStorage {
 
 const themeController = new ThemeController({
   storage: new ThemeMemoryStorageAdapter(),
-  initialMode: ThemeMode.DEFAULT,
+  initialMode: getInitialThemeMode(),
 });
 
 export const getThemeController = (): ThemeController => themeController;
diff --git a/superset-frontend/src/embedded/getInitialThemeMode.test.ts b/superset-frontend/src/embedded/getInitialThemeMode.test.ts
new file mode 100644
index 00000000000..5f9fcdef60b
--- /dev/null
+++ b/superset-frontend/src/embedded/getInitialThemeMode.test.ts
@@ -0,0 +1,66 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { ThemeMode } from '@apache-superset/core/theme';
+import { getInitialThemeMode } from './getInitialThemeMode';
+
+let locationSpy: jest.SpyInstance | undefined;
+
+afterEach(() => {
+  locationSpy?.mockRestore();
+});
+
+test('returns ThemeMode.DARK when ?themeMode=dark', () => {
+  locationSpy = jest.spyOn(window, 'location', 'get').mockReturnValue({
+    ...window.location,
+    search: '?themeMode=dark',
+  } as Location);
+  expect(getInitialThemeMode()).toBe(ThemeMode.DARK);
+});
+
+test('returns ThemeMode.SYSTEM when ?themeMode=system', () => {
+  locationSpy = jest.spyOn(window, 'location', 'get').mockReturnValue({
+    ...window.location,
+    search: '?themeMode=system',
+  } as Location);
+  expect(getInitialThemeMode()).toBe(ThemeMode.SYSTEM);
+});
+
+test('returns ThemeMode.DEFAULT when ?themeMode=light', () => {
+  locationSpy = jest.spyOn(window, 'location', 'get').mockReturnValue({
+    ...window.location,
+    search: '?themeMode=light',
+  } as Location);
+  expect(getInitialThemeMode()).toBe(ThemeMode.DEFAULT);
+});
+
+test('returns ThemeMode.DEFAULT when no themeMode param', () => {
+  locationSpy = jest.spyOn(window, 'location', 'get').mockReturnValue({
+    ...window.location,
+    search: '',
+  } as Location);
+  expect(getInitialThemeMode()).toBe(ThemeMode.DEFAULT);
+});
+
+test('returns ThemeMode.DEFAULT for an unrecognised value', () => {
+  locationSpy = jest.spyOn(window, 'location', 'get').mockReturnValue({
+    ...window.location,
+    search: '?themeMode=invalid',
+  } as Location);
+  expect(getInitialThemeMode()).toBe(ThemeMode.DEFAULT);
+});
diff --git a/superset-frontend/src/embedded/getInitialThemeMode.ts b/superset-frontend/src/embedded/getInitialThemeMode.ts
new file mode 100644
index 00000000000..922f883556a
--- /dev/null
+++ b/superset-frontend/src/embedded/getInitialThemeMode.ts
@@ -0,0 +1,35 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { ThemeMode } from '@apache-superset/core/theme';
+
+/**
+ * Reads the `?themeMode=` URL parameter from the iframe URL and returns
+ * the corresponding ThemeMode. Falls back to ThemeMode.DEFAULT when the
+ * param is absent or unrecognised.
+ *
+ * Host apps set this via `dashboardUiConfig.urlParams.themeMode` in the
+ * embed SDK, which forwards it to the iframe URL automatically.
+ */
+export function getInitialThemeMode(): ThemeMode {
+  const params = new URLSearchParams(window.location.search);
+  const themeMode = params.get('themeMode');
+  if (themeMode === 'dark') return ThemeMode.DARK;
+  if (themeMode === 'system') return ThemeMode.SYSTEM;
+  return ThemeMode.DEFAULT;
+}