From aefea8b502fa980f8758419f6801d622de20801d Mon Sep 17 00:00:00 2001
From: Dhruwang <dhruwangjariwala18@gmail.com>
Date: Wed, 7 Oct 2026 17:34:14 +0530
Subject: [PATCH 1/3] feat: add setAppearance for dark mode and forward custom
 CSS to the survey renderer [ENG-3646]

---
 apps/playground/app.json                      |   2 +-
 apps/playground/src/app.tsx                   |  45 +++++++-
 packages/react-native/README.md               |  18 ++++
 .../src/components/survey-web-view.tsx        |  38 ++++++-
 .../tests/survey-web-view-harness.test.ts     |  17 +++
 packages/react-native/src/index.ts            |  18 ++++
 .../react-native/src/lib/common/appearance.ts | 102 ++++++++++++++++++
 packages/react-native/src/lib/common/setup.ts |   7 ++
 .../src/lib/common/tests/appearance.test.ts   | 100 +++++++++++++++++
 .../src/lib/common/tests/utils.test.ts        |  35 ++++++
 packages/react-native/src/lib/common/utils.ts |  31 +++++-
 packages/react-native/src/types/config.ts     |   6 +-
 packages/react-native/src/types/survey.ts     |   8 +-
 packages/react-native/src/types/workspace.ts  |   6 ++
 14 files changed, 424 insertions(+), 9 deletions(-)
 create mode 100644 packages/react-native/src/lib/common/appearance.ts
 create mode 100644 packages/react-native/src/lib/common/tests/appearance.test.ts

diff --git a/apps/playground/app.json b/apps/playground/app.json
index f3cdaa4..cee233a 100644
--- a/apps/playground/app.json
+++ b/apps/playground/app.json
@@ -21,7 +21,7 @@
       "image": "./assets/splash.png",
       "resizeMode": "contain"
     },
-    "userInterfaceStyle": "light",
+    "userInterfaceStyle": "automatic",
     "version": "1.0.0",
     "web": {
       "favicon": "./assets/favicon.png"
diff --git a/apps/playground/src/app.tsx b/apps/playground/src/app.tsx
index c96eee3..204ad66 100644
--- a/apps/playground/src/app.tsx
+++ b/apps/playground/src/app.tsx
@@ -1,5 +1,6 @@
 import Formbricks, {
   logout,
+  setAppearance,
   setAttribute,
   setAttributes,
   setLanguage,
@@ -8,11 +9,20 @@ import Formbricks, {
 } from "@formbricks/react-native";
 import { StatusBar } from "expo-status-bar";
 import type { JSX } from "react";
-import { Button, LogBox, StyleSheet, Text, View } from "react-native";
+import {
+  Appearance,
+  Button,
+  LogBox,
+  StyleSheet,
+  Text,
+  useColorScheme,
+  View,
+} from "react-native";
 
 LogBox.ignoreAllLogs();
 
 export default function App(): JSX.Element {
+  const appTheme = useColorScheme();
   if (!process.env.EXPO_PUBLIC_FORMBRICKS_WORKSPACE_ID) {
     throw new Error("EXPO_PUBLIC_FORMBRICKS_WORKSPACE_ID is required");
   }
@@ -22,8 +32,15 @@ export default function App(): JSX.Element {
   }
 
   return (
-    <View style={styles.container}>
-      <Text>Formbricks React Native SDK Demo</Text>
+    <View
+      style={[
+        styles.container,
+        { backgroundColor: appTheme === "dark" ? "#000" : "#fff" },
+      ]}
+    >
+      <Text style={{ color: appTheme === "dark" ? "#fff" : "#000" }}>
+        Formbricks React Native SDK Demo
+      </Text>
 
       <View
         style={{
@@ -79,6 +96,23 @@ export default function App(): JSX.Element {
           }}
         />
 
+        <View style={styles.row}>
+          <Button title="Light" onPress={() => setAppearance("light")} />
+          <Button title="Dark" onPress={() => setAppearance("dark")} />
+          <Button title="System" onPress={() => setAppearance("system")} />
+        </View>
+
+        <View style={styles.row}>
+          <Button
+            title="App light"
+            onPress={() => Appearance.setColorScheme("light")}
+          />
+          <Button
+            title="App dark"
+            onPress={() => Appearance.setColorScheme("dark")}
+          />
+        </View>
+
         <Button
           title="Logout"
           onPress={() => {
@@ -111,6 +145,11 @@ export default function App(): JSX.Element {
 }
 
 const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    gap: 10,
+    justifyContent: "center",
+  },
   container: {
     flex: 1,
     backgroundColor: "#fff",
diff --git a/packages/react-native/README.md b/packages/react-native/README.md
index 4f48f97..994ec6b 100644
--- a/packages/react-native/README.md
+++ b/packages/react-native/README.md
@@ -41,3 +41,21 @@ Replace your-workspace-id with your actual workspace ID. You can find your works
 > **Note:** The `environmentId` prop is still supported as a backward-compatible alias for `workspaceId`, but it is deprecated and will be removed in a future major release. New integrations should use `workspaceId`.
 
 For more detailed guides for different frameworks, check out our [Framework Guides](https://formbricks.com/docs/getting-started/framework-guides).
+
+## Dark mode
+
+Surveys render light by default. Call `setAppearance` to change it:
+
+```ts
+import { setAppearance } from "@formbricks/react-native";
+
+setAppearance("dark"); // "light" | "dark" | "system"
+```
+
+- Works before or after `setup()`, or pass `appearance` in the `setup()` config.
+- An open survey switches in place; the typed answer and current question stay.
+- `"system"` follows **your app's** theme (`Appearance.getColorScheme()`, including `Appearance.setColorScheme`), not the phone's, and updates live. If your app keeps its theme only in JS, call `setAppearance("light" | "dark")` yourself when it changes.
+- Kept across `logout()`, forgotten on app restart, never sent to the server. An unknown value logs an error and falls back to light.
+- Needs a Formbricks server that supports dark mode; an older server keeps surveys light.
+
+Custom CSS configured in Formbricks needs no SDK call; it arrives with the workspace state.
diff --git a/packages/react-native/src/components/survey-web-view.tsx b/packages/react-native/src/components/survey-web-view.tsx
index e38f2b2..29c3b10 100644
--- a/packages/react-native/src/components/survey-web-view.tsx
+++ b/packages/react-native/src/components/survey-web-view.tsx
@@ -17,9 +17,20 @@ import {
   parseCardRectMessage,
   type TCardState,
 } from "@/components/utils/survey-touch-region";
+import {
+  getAppearance,
+  resolveAppearance,
+  type TResolvedAppearance,
+  watchResolvedAppearance,
+} from "@/lib/common/appearance";
 import { RNConfig } from "@/lib/common/config";
 import { Logger } from "@/lib/common/logger";
-import { filterSurveys, getLanguageCode, getStyling } from "@/lib/common/utils";
+import {
+  filterSurveys,
+  getCustomCss,
+  getLanguageCode,
+  getStyling,
+} from "@/lib/common/utils";
 import { EmbeddedDataStore } from "@/lib/survey/embedded-data";
 import { SurveyStore } from "@/lib/survey/store";
 import { refreshSegmentsAfterInteraction } from "@/lib/user/interaction-refresh";
@@ -56,6 +67,13 @@ export function SurveyWebView(props: SurveyWebViewProps): JSX.Element | null {
    */
   const [embeddedDataSnapshot, setEmbeddedDataSnapshot] =
     useState<TIngestedFieldsRecord>({});
+  /**
+   * The appearance the survey opens with, frozen at display like the Embedded Data bag: it feeds
+   * `source`, and a change to `source` reloads the WebView and loses the respondent's answers. Later
+   * changes reach the open survey through `injectJavaScript` below instead.
+   */
+  const [initialAppearance, setInitialAppearance] =
+    useState<TResolvedAppearance>("light");
   /** The card's state as the renderer reports it; see `TCardState` for why it has three values. */
   const [cardState, setCardState] = useState<TCardState>(undefined);
   /** The area a no-overlay survey renders over, so the WebView keeps exactly that size. */
@@ -83,6 +101,21 @@ export function SurveyWebView(props: SurveyWebViewProps): JSX.Element | null {
     };
   }, []);
 
+  // Switches an open survey in place. The listeners live only while a survey is shown, so a closed
+  // survey holds none. The first callback repeats the value the survey opened with; skipped.
+  useEffect(() => {
+    if (!showSurvey) return;
+    let applied = initialAppearance;
+    return watchResolvedAppearance((resolved) => {
+      if (resolved === applied) return;
+      applied = resolved;
+      // Optional chaining: an older server's renderer has no setAppearance and stays light.
+      webViewRef.current?.injectJavaScript(
+        `window.formbricksSurveys?.setAppearance?.(${JSON.stringify(resolved)}); true;`,
+      );
+    });
+  }, [showSurvey, initialAppearance]);
+
   useEffect(() => {
     const fetchConfig = async (): Promise<void> => {
       const config = await RNConfig.getInstance();
@@ -135,6 +168,7 @@ export function SurveyWebView(props: SurveyWebViewProps): JSX.Element | null {
      */
     const display = (): void => {
       setEmbeddedDataSnapshot(EmbeddedDataStore.getInstance().getSnapshot());
+      setInitialAppearance(resolveAppearance(getAppearance()));
       setShowSurvey(true);
     };
 
@@ -202,6 +236,8 @@ export function SurveyWebView(props: SurveyWebViewProps): JSX.Element | null {
           clickOutside,
           overlay,
           isWebEnvironment: false,
+          appearance: initialAppearance,
+          customCss: getCustomCss(settings, props.survey),
           // Passed straight through, unfiltered: the Embedded Data ingest contract lives in
           // the renderer (ENG-1845/2472), so all four mobile SDKs inherit the same allow-list,
           // coercion and size rules without each shipping a copy. The renderer drops unknown
diff --git a/packages/react-native/src/components/tests/survey-web-view-harness.test.ts b/packages/react-native/src/components/tests/survey-web-view-harness.test.ts
index fd2a537..6bff9d4 100644
--- a/packages/react-native/src/components/tests/survey-web-view-harness.test.ts
+++ b/packages/react-native/src/components/tests/survey-web-view-harness.test.ts
@@ -89,4 +89,21 @@ describe("WebView harness", () => {
     // Each "<" is emitted as the literal six-character sequence \u003c.
     expect(html).toContain("\\u003c/script>");
   });
+
+  test("hands appearance and customCss to renderSurvey as plain options", () => {
+    const html = renderHtml({
+      appUrl: "https://app.formbricks.com",
+      workspaceId: "ws-1",
+      appearance: "dark",
+      customCss: { workspace: { dark: ".a{color:red}" } },
+    });
+    expect(html).toContain('"appearance":"dark"');
+    expect(html).toContain(
+      '"customCss":{"workspace":{"dark":".a{color:red}"}}',
+    );
+  });
+
+  test("sends no customCss key when there is none", () => {
+    expect(harness()).not.toContain("customCss");
+  });
 });
diff --git a/packages/react-native/src/index.ts b/packages/react-native/src/index.ts
index 290f5e6..fbb089c 100644
--- a/packages/react-native/src/index.ts
+++ b/packages/react-native/src/index.ts
@@ -1,3 +1,7 @@
+import {
+  setAppearance as setAppearanceState,
+  type TAppearance,
+} from "@/lib/common/appearance";
 import { CommandQueue } from "@/lib/common/command-queue";
 import { Logger } from "@/lib/common/logger";
 import * as Actions from "@/lib/survey/action";
@@ -42,6 +46,19 @@ export const setLanguage = async (language: string): Promise<void> => {
   await queue.wait();
 };
 
+/**
+ * Set how surveys render: "light" (default), "dark", or "system" to follow the app's own theme
+ * (`Appearance.getColorScheme()`), not the phone's. Apps that keep their theme only in JS must pass
+ * "light" or "dark" themselves.
+ *
+ * Synchronous and never queued, so it works before `setup()`; an open survey switches in place and
+ * keeps its answers. Kept across `logout()`, forgotten on app restart, and never sent to the server.
+ * An unknown value logs an error and falls back to light.
+ */
+export const setAppearance = (appearance: TAppearance): void => {
+  setAppearanceState(appearance);
+};
+
 export const logout = async (): Promise<void> => {
   queue.add(User.logout, true);
   await queue.wait();
@@ -76,3 +93,4 @@ export const clearEmbeddedData = (...args: [] | [key: string]): void => {
 };
 
 export { Formbricks, Formbricks as default } from "@/components/formbricks";
+export type { TAppearance } from "@/lib/common/appearance";
diff --git a/packages/react-native/src/lib/common/appearance.ts b/packages/react-native/src/lib/common/appearance.ts
new file mode 100644
index 0000000..ac314e3
--- /dev/null
+++ b/packages/react-native/src/lib/common/appearance.ts
@@ -0,0 +1,102 @@
+import { Appearance as NativeAppearance } from "react-native";
+import { Logger } from "@/lib/common/logger";
+
+/** What a host app may ask for. `"system"` follows the app's own theme, never sent to the WebView. */
+export type TAppearance = "light" | "dark" | "system";
+/** What the renderer receives: always a concrete value. */
+export type TResolvedAppearance = "light" | "dark";
+
+const APPEARANCES: ReadonlySet<unknown> = new Set<TAppearance>([
+  "light",
+  "dark",
+  "system",
+]);
+
+// In memory for the process only (ENG-3452): appearance is an app setting, not a contact attribute,
+// so it is neither persisted nor sent to the server. Logout leaves it alone; a cold start is light
+// (ENG-3551).
+let appearance: TAppearance = "light";
+const listeners = new Set<() => void>();
+
+export const isAppearance = (value: unknown): value is TAppearance =>
+  APPEARANCES.has(value);
+
+export const getAppearance = (): TAppearance => appearance;
+
+/**
+ * Resolves the requested appearance to what the renderer understands. `"system"` is the app's own
+ * theme (`Appearance.getColorScheme()`, which honours `Appearance.setColorScheme` overrides), not
+ * the phone's — WebViews report the OS preference inconsistently.
+ */
+export const resolveAppearance = (
+  requested: TAppearance = appearance,
+): TResolvedAppearance => {
+  if (requested === "system") {
+    return NativeAppearance.getColorScheme() === "dark" ? "dark" : "light";
+  }
+  return requested;
+};
+
+/**
+ * Sets how surveys render. Callable before `setup()`, never queued. An unknown value logs a warning
+ * and falls back to light instead of throwing, as a bad value must not break the host app.
+ */
+export const setAppearance = (value: unknown): void => {
+  if (isAppearance(value)) {
+    appearance = value;
+  } else {
+    Logger.getInstance().error(
+      `setAppearance: unknown appearance "${String(value)}", falling back to light`,
+    );
+    appearance = "light";
+  }
+  for (const listener of listeners) listener();
+};
+
+/** Calls `listener` whenever `setAppearance` runs. Returns the unsubscribe function. */
+export const subscribeToAppearance = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/**
+ * Calls `listener` with the resolved value whenever it may have changed: on `setAppearance`, and,
+ * while the request is `"system"`, on a change of the app's theme. The native listener exists only
+ * while `"system"` is requested and is removed on the returned unsubscribe, so a closed survey
+ * holds no listener.
+ */
+export const watchResolvedAppearance = (
+  listener: (resolved: TResolvedAppearance) => void,
+): (() => void) => {
+  let removeNativeListener: (() => void) | undefined;
+
+  const sync = (): void => {
+    removeNativeListener?.();
+    removeNativeListener = undefined;
+    if (appearance === "system") {
+      const subscription = NativeAppearance.addChangeListener(() => {
+        listener(resolveAppearance());
+      });
+      removeNativeListener = () => {
+        subscription.remove();
+      };
+    }
+    listener(resolveAppearance());
+  };
+
+  const unsubscribe = subscribeToAppearance(sync);
+  sync();
+
+  return () => {
+    unsubscribe();
+    removeNativeListener?.();
+  };
+};
+
+/** Test-only: back to the cold-start state. */
+export const resetAppearance = (): void => {
+  appearance = "light";
+  listeners.clear();
+};
diff --git a/packages/react-native/src/lib/common/setup.ts b/packages/react-native/src/lib/common/setup.ts
index bd54f6a..7c76e20 100644
--- a/packages/react-native/src/lib/common/setup.ts
+++ b/packages/react-native/src/lib/common/setup.ts
@@ -1,3 +1,4 @@
+import { setAppearance } from "@/lib/common/appearance";
 import { RN_ASYNC_STORAGE_KEY, RNConfig } from "@/lib/common/config";
 import {
   addCleanupEventListeners,
@@ -265,6 +266,12 @@ export const setup = async (
 ): Promise<
   Result<void, MissingFieldError | NetworkError | MissingPersonError>
 > => {
+  // Appearance is local state, not part of the persisted config, and must be in place before the
+  // first survey renders, so it is applied here ahead of everything else, even a repeat setup.
+  if (configInput.appearance !== undefined) {
+    setAppearance(configInput.appearance);
+  }
+
   const appConfig = await RNConfig.getInstance();
 
   const logger = Logger.getInstance();
diff --git a/packages/react-native/src/lib/common/tests/appearance.test.ts b/packages/react-native/src/lib/common/tests/appearance.test.ts
new file mode 100644
index 0000000..ac1b3e9
--- /dev/null
+++ b/packages/react-native/src/lib/common/tests/appearance.test.ts
@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+const getColorScheme = vi.fn();
+const addChangeListener = vi.fn();
+
+vi.mock("react-native", () => ({
+  Platform: { OS: "ios" },
+  Appearance: {
+    getColorScheme: (): unknown => getColorScheme(),
+    addChangeListener: (cb: () => void): unknown => addChangeListener(cb),
+  },
+}));
+
+const load = async () => import("@/lib/common/appearance");
+
+describe("appearance", () => {
+  const remove = vi.fn();
+
+  beforeEach(() => {
+    addChangeListener.mockReturnValue({ remove });
+    getColorScheme.mockReturnValue("light");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("defaults to light", async () => {
+    const { getAppearance, resolveAppearance } = await load();
+    expect(getAppearance()).toBe("light");
+    expect(resolveAppearance()).toBe("light");
+  });
+
+  test("light and dark win over the app theme", async () => {
+    getColorScheme.mockReturnValue("dark");
+    const { setAppearance, resolveAppearance } = await load();
+    setAppearance("light");
+    expect(resolveAppearance()).toBe("light");
+    getColorScheme.mockReturnValue("light");
+    setAppearance("dark");
+    expect(resolveAppearance()).toBe("dark");
+  });
+
+  test('"system" resolves to the app theme and never to "system"', async () => {
+    const { setAppearance, resolveAppearance } = await load();
+    setAppearance("system");
+    getColorScheme.mockReturnValue("dark");
+    expect(resolveAppearance()).toBe("dark");
+    getColorScheme.mockReturnValue(null);
+    expect(resolveAppearance()).toBe("light");
+  });
+
+  test("an unknown value falls back to light without throwing", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const { setAppearance, getAppearance } = await load();
+    setAppearance("dark");
+    expect(() => {
+      setAppearance("sepia");
+    }).not.toThrow();
+    expect(getAppearance()).toBe("light");
+  });
+
+  test("watchResolvedAppearance reports setAppearance changes", async () => {
+    const { setAppearance, watchResolvedAppearance } = await load();
+    const listener = vi.fn();
+    const stop = watchResolvedAppearance(listener);
+    expect(listener).toHaveBeenLastCalledWith("light");
+    setAppearance("dark");
+    expect(listener).toHaveBeenLastCalledWith("dark");
+    stop();
+    listener.mockClear();
+    setAppearance("light");
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  test('"system" follows live app theme changes and removes its listener on stop', async () => {
+    const { setAppearance, watchResolvedAppearance } = await load();
+    setAppearance("system");
+    const listener = vi.fn();
+    const stop = watchResolvedAppearance(listener);
+    expect(addChangeListener).toHaveBeenCalledTimes(1);
+
+    getColorScheme.mockReturnValue("dark");
+    (addChangeListener.mock.calls[0]?.[0] as () => void)();
+    expect(listener).toHaveBeenLastCalledWith("dark");
+
+    stop();
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  test('leaving "system" drops the native listener', async () => {
+    const { setAppearance, watchResolvedAppearance } = await load();
+    setAppearance("system");
+    const stop = watchResolvedAppearance(vi.fn());
+    setAppearance("dark");
+    expect(remove).toHaveBeenCalledTimes(1);
+    stop();
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/react-native/src/lib/common/tests/utils.test.ts b/packages/react-native/src/lib/common/tests/utils.test.ts
index 0afa67e..c350d77 100644
--- a/packages/react-native/src/lib/common/tests/utils.test.ts
+++ b/packages/react-native/src/lib/common/tests/utils.test.ts
@@ -5,6 +5,7 @@ import {
   delayedResult,
   diffInDays,
   filterSurveys,
+  getCustomCss,
   getDefaultLanguageCode,
   getLanguageCode,
   getStyling,
@@ -17,6 +18,7 @@ import type {
   TWorkspaceStateSettings,
 } from "@/types/config";
 import type { TSurvey } from "@/types/survey";
+import type { TCustomCss } from "@/types/workspace";
 
 const mockSurveyId1 = "e3kxlpnzmdp84op9qzxl9olj";
 const mockSurveyId2 = "qo9rwjmms42hoy3k85fp8vgu";
@@ -497,3 +499,36 @@ describe("utils.ts", () => {
     });
   });
 });
+
+describe("getCustomCss", () => {
+  const settings = (customCss?: TCustomCss): TWorkspaceStateSettings =>
+    ({ customCss }) as TWorkspaceStateSettings;
+  const survey = (customCss?: TCustomCss): TSurvey =>
+    ({ customCss }) as TSurvey;
+
+  test("sends no prop when neither scope has CSS", () => {
+    expect(getCustomCss(settings(), survey())).toBeUndefined();
+    expect(getCustomCss(settings({}), survey({ light: "" }))).toBeUndefined();
+  });
+
+  test("passes workspace and survey CSS through untouched", () => {
+    expect(
+      getCustomCss(
+        settings({ light: ".a{color:red}", dark: ".a{color:blue}" }),
+        survey({ dark: ".b{margin:0}" }),
+      ),
+    ).toEqual({
+      workspace: { light: ".a{color:red}", dark: ".a{color:blue}" },
+      survey: { dark: ".b{margin:0}" },
+    });
+  });
+
+  test("omits an empty scope and empty modes instead of sending null", () => {
+    const result = getCustomCss(
+      settings({ light: ".a{}", dark: undefined }),
+      survey(),
+    );
+    expect(result).toEqual({ workspace: { light: ".a{}" } });
+    expect(result).not.toHaveProperty("survey");
+  });
+});
diff --git a/packages/react-native/src/lib/common/utils.ts b/packages/react-native/src/lib/common/utils.ts
index fd44ed1..b5f5140 100644
--- a/packages/react-native/src/lib/common/utils.ts
+++ b/packages/react-native/src/lib/common/utils.ts
@@ -4,8 +4,8 @@ import type {
   TWorkspaceStateSettings,
 } from "@/types/config";
 import type { Result } from "@/types/error";
-import type { TSurvey } from "@/types/survey";
-import type { TWorkspaceStyling } from "@/types/workspace";
+import type { SurveyContainerProps, TSurvey } from "@/types/survey";
+import type { TCustomCss, TWorkspaceStyling } from "@/types/workspace";
 
 // Helper function to calculate difference in days between two dates
 export const diffInDays = (date1: Date, date2: Date): number => {
@@ -161,6 +161,33 @@ export const getStyling = (
   return settings.styling;
 };
 
+/**
+ * Builds the renderer's `customCss` prop from the workspace and survey CSS, passing the compiled
+ * strings through untouched. Empty fields are omitted rather than sent as `null`: the renderer
+ * rejects the whole prop on a null inside a scope. Returns `undefined` when there is no CSS at all,
+ * so the prop is never sent.
+ */
+export const getCustomCss = (
+  settings: TWorkspaceStateSettings,
+  survey: TSurvey,
+): SurveyContainerProps["customCss"] => {
+  const pick = (css: TCustomCss | undefined): TCustomCss | undefined => {
+    const picked: TCustomCss = {};
+    if (css?.light) picked.light = css.light;
+    if (css?.dark) picked.dark = css.dark;
+    return picked.light || picked.dark ? picked : undefined;
+  };
+
+  const workspace = pick(settings.customCss);
+  const surveyCss = pick(survey.customCss);
+  if (!workspace && !surveyCss) return undefined;
+
+  return {
+    ...(workspace && { workspace }),
+    ...(surveyCss && { survey: surveyCss }),
+  };
+};
+
 export const getDefaultLanguageCode = (survey: TSurvey): string | undefined => {
   const defaultSurveyLanguage = survey.languages.find((surveyLanguage) => {
     return surveyLanguage.default;
diff --git a/packages/react-native/src/types/config.ts b/packages/react-native/src/types/config.ts
index 6a12e43..9a968a2 100644
--- a/packages/react-native/src/types/config.ts
+++ b/packages/react-native/src/types/config.ts
@@ -1,9 +1,10 @@
 import { z } from "zod";
+import type { TAppearance } from "@/lib/common/appearance";
 import type { TResponseUpdate } from "@/types/response";
 import type { TFileUploadParams } from "@/types/storage";
 import type { TActionClass } from "./action-class";
 import type { TSurvey } from "./survey";
-import type { TWorkspace, TWorkspaceStyling } from "./workspace";
+import type { TCustomCss, TWorkspace, TWorkspaceStyling } from "./workspace";
 
 export type TWorkspaceStateSettings = Pick<
   TWorkspace,
@@ -14,6 +15,7 @@ export type TWorkspaceStateSettings = Pick<
   | "inAppSurveyBranding"
 > & {
   styling: TWorkspaceStyling;
+  customCss?: TCustomCss;
 };
 
 export type TWorkspaceStateActionClass = Pick<
@@ -69,6 +71,8 @@ export interface TConfigInput {
   environmentId?: string;
   workspaceId?: string;
   appUrl: string;
+  /** How surveys render: "light" (default), "dark", or "system" to follow the app's theme. */
+  appearance?: TAppearance;
 }
 
 /**
diff --git a/packages/react-native/src/types/survey.ts b/packages/react-native/src/types/survey.ts
index d483dd2..74f88e0 100644
--- a/packages/react-native/src/types/survey.ts
+++ b/packages/react-native/src/types/survey.ts
@@ -5,7 +5,7 @@ import type {
 } from "@/types/response";
 import type { TFileUploadParams, TUploadFileConfig } from "@/types/storage";
 import type { TOverlay } from "./common";
-import type { TWorkspaceStyling } from "./workspace";
+import type { TCustomCss, TWorkspaceStyling } from "./workspace";
 
 export interface TJsFileUploadParams {
   file: {
@@ -85,10 +85,16 @@ export interface SurveyContainerProps
   singleUseId?: string;
   singleUseResponseId?: string;
   isWebEnvironment?: boolean;
+  appearance?: "light" | "dark";
+  customCss?: {
+    workspace?: TCustomCss;
+    survey?: TCustomCss;
+  };
 }
 
 export interface TSurvey {
   id: string;
+  customCss?: TCustomCss;
   welcomeCard: {
     enabled: boolean;
     headline?: Record<string, string>;
diff --git a/packages/react-native/src/types/workspace.ts b/packages/react-native/src/types/workspace.ts
index 95e79c5..8353d50 100644
--- a/packages/react-native/src/types/workspace.ts
+++ b/packages/react-native/src/types/workspace.ts
@@ -1,6 +1,12 @@
 import type { TOverlay } from "./common";
 import type { TBaseStyling } from "./styling";
 
+/** Compiled custom CSS for one scope; either mode may be absent. Passed to the renderer untouched. */
+export interface TCustomCss {
+  light?: string;
+  dark?: string;
+}
+
 export interface TWorkspace {
   id: string;
   createdAt: Date;

From c905ac985a5f1972c92a2f3c48964dd5ef6a7147 Mon Sep 17 00:00:00 2001
From: Javi Aguilar <122741+itsjavi@users.noreply.github.com>
Date: Thu, 8 Oct 2026 18:56:41 +0200
Subject: [PATCH 2/3] fix: send appearance changes made while the survey loads
 [ENG-3646]

A setAppearance call before the renderer existed was injected as a no-op
but still recorded as applied, so the survey stayed light and repeats were
deduplicated. The page now posts onSurveyRendered and the host holds changes
until then, sending the latest one if it differs from the initial value.
---
 .../src/components/survey-web-view.tsx        | 42 ++++++++++++---
 .../components/tests/appearance-sync.test.ts  | 51 +++++++++++++++++++
 .../tests/survey-web-view-harness.test.ts     | 14 +++++
 .../src/components/utils/appearance-sync.ts   | 43 ++++++++++++++++
 4 files changed, 143 insertions(+), 7 deletions(-)
 create mode 100644 packages/react-native/src/components/tests/appearance-sync.test.ts
 create mode 100644 packages/react-native/src/components/utils/appearance-sync.ts

diff --git a/packages/react-native/src/components/survey-web-view.tsx b/packages/react-native/src/components/survey-web-view.tsx
index 29c3b10..8cbe603 100644
--- a/packages/react-native/src/components/survey-web-view.tsx
+++ b/packages/react-native/src/components/survey-web-view.tsx
@@ -10,6 +10,7 @@ import {
   View,
 } from "react-native";
 import { WebView, type WebViewMessageEvent } from "react-native-webview";
+import { createAppearanceSync } from "@/components/utils/appearance-sync";
 import { getSurveyScriptUrl } from "@/components/utils/survey-script-url";
 import {
   androidKeyboardPadding,
@@ -43,6 +44,18 @@ logger.configure({ logLevel: __DEV__ ? "debug" : "error" });
 
 const surveyStore = SurveyStore.getInstance();
 
+/** Switches the open survey's appearance; `undefined` means there is nothing to send. */
+const injectAppearance = (
+  webView: WebView | null,
+  resolved: TResolvedAppearance | undefined,
+): void => {
+  if (resolved === undefined) return;
+  // Optional chaining: an older server's renderer has no setAppearance and stays light.
+  webView?.injectJavaScript(
+    `window.formbricksSurveys?.setAppearance?.(${JSON.stringify(resolved)}); true;`,
+  );
+};
+
 interface SurveyWebViewProps {
   readonly survey: TSurvey;
 }
@@ -103,16 +116,16 @@ export function SurveyWebView(props: SurveyWebViewProps): JSX.Element | null {
 
   // Switches an open survey in place. The listeners live only while a survey is shown, so a closed
   // survey holds none. The first callback repeats the value the survey opened with; skipped.
+  // Changes made before the renderer exists wait for its `onSurveyRendered` message (see
+  // `createAppearanceSync`), or they would be dropped and then deduplicated forever.
+  const appearanceSyncRef = useRef(createAppearanceSync());
+
   useEffect(() => {
     if (!showSurvey) return;
-    let applied = initialAppearance;
+    const appearanceSync = appearanceSyncRef.current;
+    appearanceSync.reset(initialAppearance); // the value baked into the HTML
     return watchResolvedAppearance((resolved) => {
-      if (resolved === applied) return;
-      applied = resolved;
-      // Optional chaining: an older server's renderer has no setAppearance and stays light.
-      webViewRef.current?.injectJavaScript(
-        `window.formbricksSurveys?.setAppearance?.(${JSON.stringify(resolved)}); true;`,
-      );
+      injectAppearance(webViewRef.current, appearanceSync.onChange(resolved));
     });
   }, [showSurvey, initialAppearance]);
 
@@ -268,6 +281,20 @@ export function SurveyWebView(props: SurveyWebViewProps): JSX.Element | null {
             data: unknown;
           };
 
+          // Handled before the strict schema below, which would reject this message.
+          if (
+            (unvalidatedMessage as { onSurveyRendered?: unknown })
+              .onSurveyRendered === true
+          ) {
+            injectAppearance(
+              webViewRef.current,
+              appearanceSyncRef.current.onRendered(
+                resolveAppearance(getAppearance()),
+              ),
+            );
+            return;
+          }
+
           if (unvalidatedMessage.type === "CardRect") {
             const card = parseCardRectMessage(unvalidatedMessage.data);
             if (card === undefined) {
@@ -631,6 +658,7 @@ export const renderHtml = (
         };
 
         window.formbricksSurveys.renderSurvey(surveyProps);
+        window.ReactNativeWebView.postMessage(JSON.stringify({ onSurveyRendered: true }));
       }
 
       const script = document.createElement("script");
diff --git a/packages/react-native/src/components/tests/appearance-sync.test.ts b/packages/react-native/src/components/tests/appearance-sync.test.ts
new file mode 100644
index 0000000..bbed906
--- /dev/null
+++ b/packages/react-native/src/components/tests/appearance-sync.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, test } from "vitest";
+import { createAppearanceSync } from "@/components/utils/appearance-sync";
+
+describe("createAppearanceSync", () => {
+  test("sends nothing before the survey has rendered", () => {
+    const sync = createAppearanceSync();
+    sync.reset("light");
+
+    expect(sync.onChange("dark")).toBeUndefined();
+    expect(sync.onChange("dark")).toBeUndefined();
+  });
+
+  /** The bug: a change made while the bundle loads was dropped, and later repeats deduplicated. */
+  test("sends the latest value on render when it changed while loading", () => {
+    const sync = createAppearanceSync();
+    sync.reset("light");
+    sync.onChange("dark");
+
+    expect(sync.onRendered("dark")).toBe("dark");
+    // Recorded as applied, so a repeat is a no-op.
+    expect(sync.onChange("dark")).toBeUndefined();
+  });
+
+  test("sends nothing on render when the value matches the one baked into the HTML", () => {
+    const sync = createAppearanceSync();
+    sync.reset("dark");
+
+    expect(sync.onRendered("dark")).toBeUndefined();
+  });
+
+  test("sends only real changes once rendered", () => {
+    const sync = createAppearanceSync();
+    sync.reset("light");
+    sync.onRendered("light");
+
+    expect(sync.onChange("light")).toBeUndefined();
+    expect(sync.onChange("dark")).toBe("dark");
+    expect(sync.onChange("dark")).toBeUndefined();
+    expect(sync.onChange("light")).toBe("light");
+  });
+
+  test("reset for a new survey waits for that survey to render again", () => {
+    const sync = createAppearanceSync();
+    sync.reset("light");
+    sync.onRendered("light");
+    sync.reset("dark");
+
+    expect(sync.onChange("light")).toBeUndefined();
+    expect(sync.onRendered("light")).toBe("light");
+  });
+});
diff --git a/packages/react-native/src/components/tests/survey-web-view-harness.test.ts b/packages/react-native/src/components/tests/survey-web-view-harness.test.ts
index 6bff9d4..caab2ba 100644
--- a/packages/react-native/src/components/tests/survey-web-view-harness.test.ts
+++ b/packages/react-native/src/components/tests/survey-web-view-harness.test.ts
@@ -44,6 +44,20 @@ describe("WebView harness", () => {
     expect(propsBlock).toContain("onClose,");
   });
 
+  /** The host holds appearance changes until this message; without it they never reach the survey. */
+  test("posts onSurveyRendered right after renderSurvey", () => {
+    const html = harness();
+    const renderAt = html.indexOf(
+      "window.formbricksSurveys.renderSurvey(surveyProps);",
+    );
+    const postAt = html.indexOf(
+      "window.ReactNativeWebView.postMessage(JSON.stringify({ onSurveyRendered: true }))",
+    );
+
+    expect(renderAt).toBeGreaterThan(-1);
+    expect(postAt).toBeGreaterThan(renderAt);
+  });
+
   /** The card rect is how a no-overlay survey lets touches through; unwired, it silently blocks. */
   test("wires onCardRectChange into renderSurvey's props and posts it back", () => {
     const html = harness();
diff --git a/packages/react-native/src/components/utils/appearance-sync.ts b/packages/react-native/src/components/utils/appearance-sync.ts
new file mode 100644
index 0000000..721e0c3
--- /dev/null
+++ b/packages/react-native/src/components/utils/appearance-sync.ts
@@ -0,0 +1,43 @@
+import type { TResolvedAppearance } from "@/lib/common/appearance";
+
+/**
+ * Decides when an open survey's appearance has to be sent to the renderer.
+ *
+ * Until the renderer reports `onSurveyRendered` there is no `formbricksSurveys.setAppearance` to
+ * call, so an injection would be a no-op. Changes made meanwhile therefore wait, and the rendered
+ * handshake sends the latest one. Each method returns the value to inject, or `undefined` when
+ * nothing needs sending; a returned value is recorded as applied.
+ */
+export interface TAppearanceSync {
+  /** A survey is shown with `initial` baked into its HTML; it has not rendered yet. */
+  reset: (initial: TResolvedAppearance) => void;
+  /** The resolved appearance changed while the survey is shown. */
+  onChange: (resolved: TResolvedAppearance) => TResolvedAppearance | undefined;
+  /** The renderer exists; `current` is the appearance resolved right now. */
+  onRendered: (current: TResolvedAppearance) => TResolvedAppearance | undefined;
+}
+
+export const createAppearanceSync = (): TAppearanceSync => {
+  let rendered = false;
+  let applied: TResolvedAppearance = "light";
+
+  const sendIfChanged = (
+    resolved: TResolvedAppearance,
+  ): TResolvedAppearance | undefined => {
+    if (resolved === applied) return undefined;
+    applied = resolved;
+    return resolved;
+  };
+
+  return {
+    reset: (initial) => {
+      rendered = false;
+      applied = initial;
+    },
+    onChange: (resolved) => (rendered ? sendIfChanged(resolved) : undefined),
+    onRendered: (current) => {
+      rendered = true;
+      return sendIfChanged(current);
+    },
+  };
+};

From a0ea8512f57ba3696e5fca470377c6c14f2a2c79 Mon Sep 17 00:00:00 2001
From: Javi Aguilar <122741+itsjavi@users.noreply.github.com>
Date: Thu, 8 Oct 2026 18:57:04 +0200
Subject: [PATCH 3/3] fix: drop the white loading view over dark surveys
 [ENG-3646]

startInLoadingState without renderLoading shows react-native-webview's
default loader, an opaque white full-screen view, until the page loads. The
WebView is already transparent and the renderer paints the card once ready,
matching the iOS and Android SDKs.
---
 packages/react-native/src/components/survey-web-view.tsx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/react-native/src/components/survey-web-view.tsx b/packages/react-native/src/components/survey-web-view.tsx
index 8cbe603..6e99b10 100644
--- a/packages/react-native/src/components/survey-web-view.tsx
+++ b/packages/react-native/src/components/survey-web-view.tsx
@@ -262,7 +262,8 @@ export function SurveyWebView(props: SurveyWebViewProps): JSX.Element | null {
       contentMode="mobile"
       javaScriptEnabled
       domStorageEnabled
-      startInLoadingState
+      // No `startInLoadingState`: its default loader is an opaque white full-screen view, which
+      // flashes over dark apps. The transparent WebView shows nothing until the card paints.
       scrollEnabled={false}
       setSupportMultipleWindows={false}
       onShouldStartLoadWithRequest={(event) => {