Dark / Light Mode

This guide demonstrates how to implement dark and light mode themes in your RedwoodSDK application. The approach uses cookies to persist user preferences and direct DOM manipulation to toggle themes, without requiring a React context provider.

Overview

The theme system supports three modes:

dark: Always use dark mode
light: Always use light mode
system: Follow the user’s system preference

The implementation follows this flow:

worker (read theme from cookie)
  ⮑ Document (set class on <html>, calculate system theme before render)
     ⮑ Page components
        ⮑ ThemeToggle (client component that updates DOM and cookie)

Implementation

Read theme from cookie in the worker

In your src/worker.tsx, read the theme cookie and add it to the app context:

1
import { render, route } from "rwsdk/router";
2
import { defineApp } from "rwsdk/worker";
3

4
import { Document } from "@/app/Document";
5
import { Home } from "@/app/pages/Home";
6

7
export interface AppContext {
8
  theme?: "dark" | "light" | "system";
9
}
10

11
export default defineApp([
12
  ({ ctx, request }) => {
13
    // Read theme from cookie
14
    const cookie = request.headers.get("Cookie");
15
    const match = cookie?.match(/theme=([^;]+)/);
16
    ctx.theme = (match?.[1] as "dark" | "light" | "system") || "system";
17
  },
18
  render(Document, [route("/", Home)]),
19
]);

Create a server action to set the theme

Create a server function that updates the theme cookie:

1
"use server";
2

3
import { requestInfo } from "rwsdk/worker";
4

5
export async function setTheme(theme: "dark" | "light" | "system") {
6
  requestInfo.response.headers.set(
7
    "Set-Cookie",
8
    `theme=${theme}; Path=/; Max-Age=31536000; SameSite=Lax`,
9
  );
10
}

Update Document to set theme class before render

The Document component needs to set the theme class on the <html> element before React hydrates to prevent FOUC. This requires a small inline script:

1
import React from "react";
2
import { requestInfo } from "rwsdk/worker";
3
import stylesUrl from "./styles.css?url";
4

5
export const Document: React.FC<{ children: React.ReactNode }> = ({
6
  children,
7
}) => {
8
  const theme = requestInfo?.ctx?.theme || "system";
9

10
  return (
11
    <html lang="en">
12
      <head>
13
        <meta charSet="utf-8" />
14
        <meta
15
          name="viewport"
16
          content="width=device-width, initial-scale=1"
17
        />
18
        <title>My App</title>
19
        <link rel="modulepreload" href="/src/client.tsx" />
20
        <link rel="stylesheet" href={stylesUrl} />
21
      </head>
22
      <body>
23
        {/* Script to set theme class before React hydrates */}
24
        <script
25
          dangerouslySetInnerHTML={{
26
            __html: `
27
              (function() {
28
                const theme = ${JSON.stringify(theme)};
29
                const isSystemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
30
                const shouldBeDark = theme === 'dark' || (theme === 'system' && isSystemDark);
31
                if (shouldBeDark) {
32
                  document.documentElement.classList.add('dark');
33
                } else {
34
                  document.documentElement.classList.remove('dark');
35
                }
36
                document.documentElement.setAttribute('data-theme', theme);
37
              })();
38
            `,
39
          }}
40
        />
41
        <div id="root">{children}</div>
42
        <script>import("/src/client.tsx")</script>
43
      </body>
44
    </html>
45
  );
46
};

Create a theme toggle component

Create a client component that toggles the theme by directly manipulating the DOM and calling the server action:

1
"use client";
2

3
import { useEffect, useRef, useState } from "react";
4
import { setTheme } from "../actions/setTheme";
5

6
type Theme = "dark" | "light" | "system";
7

8
export function ThemeToggle({ initialTheme }: { initialTheme: Theme }) {
9
  const [theme, setThemeState] = useState<Theme>(initialTheme);
10
  const isInitialMount = useRef(true);
11

12
  // Update DOM when theme changes
13
  useEffect(() => {
14
    const root = document.documentElement;
15
    const shouldBeDark =
16
      theme === "dark" ||
17
      (theme === "system" &&
18
        window.matchMedia("(prefers-color-scheme: dark)").matches);
19

20
    if (shouldBeDark) {
21
      root.classList.add("dark");
22
    } else {
23
      root.classList.remove("dark");
24
    }
25

26
    // Set data attribute for consistency
27
    root.setAttribute("data-theme", theme);
28

29
    // Persist to cookie via server action (only when theme actually changes, not on initial mount)
30
    if (!isInitialMount.current) {
31
      setTheme(theme).catch((error) => {
32
        console.error("Failed to set theme:", error);
33
      });
34
    } else {
35
      isInitialMount.current = false;
36
    }
37
  }, [theme]);
38

39
  // Listen for system theme changes when theme is "system"
40
  useEffect(() => {
41
    if (theme !== "system") return;
42

43
    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
44
    const handleChange = () => {
45
      const root = document.documentElement;
46
      if (mediaQuery.matches) {
47
        root.classList.add("dark");
48
      } else {
49
        root.classList.remove("dark");
50
      }
51
    };
52

53
    mediaQuery.addEventListener("change", handleChange);
54
    return () => mediaQuery.removeEventListener("change", handleChange);
55
  }, [theme]);
56

57
  const toggleTheme = () => {
58
    // Cycle through: system -> light -> dark -> system
59
    if (theme === "system") {
60
      setThemeState("light");
61
    } else if (theme === "light") {
62
      setThemeState("dark");
63
    } else {
64
      setThemeState("system");
65
    }
66
  };
67

68
  return (
69
    <div className="flex items-center gap-4">
70
      <span>Current theme: {theme}</span>
71
      <button
72
        onClick={toggleTheme}
73
        className="px-4 py-2 rounded bg-gray-200 dark:bg-gray-800 text-gray-800 dark:text-gray-200 transition-colors"
74
        aria-label="Toggle theme"
75
      >
76
        {theme === "dark" ? "☀️" : theme === "light" ? "🌙" : "💻"}
77
      </button>
78
    </div>
79
  );
80
}

Use the theme toggle in your pages

Pass the theme from the context to your toggle component:

1
import { RequestInfo } from "rwsdk/worker";
2
import { ThemeToggle } from "../components/ThemeToggle";
3

4
export function Home({ ctx }: RequestInfo) {
5
  const theme = ctx.theme || "system";
6

7
  return (
8
    <div>
9
      <h1>Welcome</h1>
10
      <ThemeToggle initialTheme={theme} />
11
    </div>
12
  );
13
}

Reading the Current Theme

The ThemeToggle component above includes a display of the current theme. If you need to read the current theme in a separate client component, you can check the DOM directly:

1
"use client";
2

3
import { useEffect, useState } from "react";
4

5
export function MyComponent() {
6
  const [isDark, setIsDark] = useState(false);
7

8
  useEffect(() => {
9
    // Check if dark class is present
10
    setIsDark(document.documentElement.classList.contains("dark"));
11

12
    // Optional: Listen for changes
13
    const observer = new MutationObserver(() => {
14
      setIsDark(document.documentElement.classList.contains("dark"));
15
    });
16

17
    observer.observe(document.documentElement, {
18
      attributes: true,
19
      attributeFilter: ["class"],
20
    });
21

22
    return () => observer.disconnect();
23
  }, []);
24

25
  return (
26
    <div>
27
      <p>Current theme: {isDark ? "dark" : "light"}</p>
28
    </div>
29
  );
30
}

CSS Styling

With Tailwind CSS, you can use the dark: variant to style elements differently in dark mode:

1
@import "tailwindcss";
2

3
@custom-variant dark (&:is(.dark *));
4

5
/* Your custom styles */
6
.my-component {
7
  background-color: white;
8
  color: black;
9
}
10

11
.dark .my-component {
12
  background-color: #1a1a1a;
13
  color: white;
14
}

Or with Tailwind utility classes:

1
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
2
  Content
3
</div>

Alternative: Data Attributes

If you prefer using data attributes instead of class names, you can modify the Document and toggle component:

1
// In the script
2
document.documentElement.setAttribute("data-theme", theme);

1
// In the useEffect
2
root.setAttribute("data-theme", theme);

Then in your CSS:

1
[data-theme="dark"] .my-component {
2
  background-color: #1a1a1a;
3
}