From 94996643f090b0d8986a5517a91f14b598d1d3cc Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 25 May 2026 07:48:04 +0000
Subject: [PATCH] docs: document theme prop for React SDK components

---
 references/react-sdk.mdx | 57 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/references/react-sdk.mdx b/references/react-sdk.mdx
index f9988dba..928a7491 100644
--- a/references/react-sdk.mdx
+++ b/references/react-sdk.mdx
@@ -101,6 +101,7 @@ type DashboardProps = {
   token: string | Promise<string>;  // JWT (can be async)
 
   // Optional
+  theme?: 'light' | 'dark';         // Force light or dark color scheme
   styles?: {
     backgroundColor?: string;       // Background color or 'transparent'
     fontFamily?: string;            // Font family for all text
@@ -200,6 +201,7 @@ type ChartProps = {
   token: string | Promise<string>;  // JWT with type: 'chart'
 
   // Optional
+  theme?: 'light' | 'dark';         // Force light or dark color scheme
   styles?: {
     backgroundColor?: string;       // Background color or 'transparent'
     fontFamily?: string;            // Font family for all text
@@ -278,6 +280,7 @@ type ExploreProps = {
   token: string | Promise<string>;  // JWT with canExplore: true
 
   // Optional
+  theme?: 'light' | 'dark';         // Force light or dark color scheme
   styles?: {
     backgroundColor?: string;       // Background color or 'transparent'
     fontFamily?: string;            // Font family for all text
@@ -465,6 +468,60 @@ Sets the background for the embedded content. Can be any color value or `'transp
 />
 ```
 
+## Light and dark mode
+
+Use the `theme` prop to render embedded content in either `'light'` or `'dark'` mode. This is typically driven by the host application's own theme state, so the embedded dashboard, chart, or explore matches the surrounding UI.
+
+```tsx
+<Lightdash.Dashboard
+  instanceUrl={lightdashUrl}
+  token={lightdashToken}
+  theme="dark"
+/>
+```
+
+The `theme` prop is supported on `Lightdash.Dashboard`, `Lightdash.Chart`, and `Lightdash.Explore`.
+
+<Info>
+When `theme` is set, the SDK forces the Mantine color scheme and ignores any user-toggled preference stored in the embed. Omit the prop to let the embed use its default (light) color scheme.
+</Info>
+
+### Syncing with your app's theme
+
+Pass your app's current theme value directly to the SDK so the embed re-renders when it changes:
+
+```tsx
+import Lightdash from '@lightdash/sdk';
+import { useState } from 'react';
+
+function EmbeddedDashboard() {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+
+  return (
+    <Lightdash.Dashboard
+      instanceUrl={lightdashUrl}
+      token={lightdashToken}
+      theme={theme}
+    />
+  );
+}
+```
+
+### Combining with `styles.backgroundColor`
+
+When `theme` is set, the embed uses the matching Mantine body background by default. If you also pass `styles.backgroundColor`, your value takes precedence:
+
+```tsx
+<Lightdash.Dashboard
+  instanceUrl={lightdashUrl}
+  token={lightdashToken}
+  theme="dark"
+  styles={{
+    backgroundColor: '#0b0b0f', // Overrides the default dark background
+  }}
+/>
+```
+
 ## Color palettes
 
 You can customize the appearance of embedded dashboards using color palettes. Define multiple color palettes in your organization settings, then apply them to embedded dashboards using the `paletteUuid` prop.