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 { defineApp, render, route, setCommonHeaders } from "rwsdk/router";
2
import Document from "./app/Document";
3
import Home from "./app/pages/Home";
4

5
interface AppContext {
6
  theme?: "dark" | "light" | "system";
7
}
8

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

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 type { DocumentProps } from "rwsdk/router";
2

3
export default function Document({ children, requestInfo }: DocumentProps) {
4
  const theme = requestInfo?.ctx?.theme || "system";
5

6
  return (
7
    <html lang="en">
8
      <head>
9
        <meta charSet="utf-8" />
10
        <meta
11
          name="viewport"
12
          content="width=device-width, initial-scale=1"
13
        />
14
        <title>My App</title>
15
      </head>
16
      <body>
17
        {/* Script to set theme class before React hydrates */}
18
        <script
19
          dangerouslySetInnerHTML={{
20
            __html: `
21
              (function() {
22
                const theme = ${JSON.stringify(theme)};
23
                const isSystemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
24
                const shouldBeDark = theme === 'dark' || (theme === 'system' && isSystemDark);
25
                if (shouldBeDark) {
26
                  document.documentElement.classList.add('dark');
27
                } else {
28
                  document.documentElement.classList.remove('dark');
29
                }
30
              })();
31
            `,
32
          }}
33
        />
34
        {children}
35
      </body>
36
    </html>
37
  );
38
}

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, 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

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

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

25
    // Persist to cookie via server action
26
    setTheme(theme);
27
  }, [theme]);
28

29
  // Listen for system theme changes when theme is "system"
30
  useEffect(() => {
31
    if (theme !== "system") return;
32

33
    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
34
    const handleChange = () => {
35
      const root = document.documentElement;
36
      if (mediaQuery.matches) {
37
        root.classList.add("dark");
38
      } else {
39
        root.classList.remove("dark");
40
      }
41
    };
42

43
    mediaQuery.addEventListener("change", handleChange);
44
    return () => mediaQuery.removeEventListener("change", handleChange);
45
  }, [theme]);
46

47
  const toggleTheme = () => {
48
    // Cycle through: system -> light -> dark -> system
49
    if (theme === "system") {
50
      setThemeState("light");
51
    } else if (theme === "light") {
52
      setThemeState("dark");
53
    } else {
54
      setThemeState("system");
55
    }
56
  };
57

58
  return (
59
    <button
60
      onClick={toggleTheme}
61
      className="px-4 py-2 rounded bg-gray-200 dark:bg-gray-800"
62
      aria-label="Toggle theme"
63
    >
64
      {theme === "dark" ? "☀️" : theme === "light" ? "🌙" : "💻"}
65
    </button>
66
  );
67
}

Use the theme toggle in your pages

Pass the theme from requestInfo to your toggle component:

1
import type { PageProps } from "rwsdk/router";
2
import { ThemeToggle } from "../components/ThemeToggle";
3

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

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

Alternative: Simpler Toggle (Dark/Light Only)

If you only need dark and light modes (no system preference), you can simplify the toggle:

1
"use client";
2

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

6
export function ThemeToggle({
7
  initialTheme,
8
}: {
9
  initialTheme: "dark" | "light";
10
}) {
11
  const [isDark, setIsDark] = useState(initialTheme === "dark");
12

13
  useEffect(() => {
14
    const root = document.documentElement;
15
    if (isDark) {
16
      root.classList.add("dark");
17
      setTheme("dark");
18
    } else {
19
      root.classList.remove("dark");
20
      setTheme("light");
21
    }
22
  }, [isDark]);
23

24
  return (
25
    <button
26
      onClick={() => setIsDark(!isDark)}
27
      className="px-4 py-2 rounded bg-gray-200 dark:bg-gray-800"
28
      aria-label="Toggle theme"
29
    >
30
      {isDark ? "☀️" : "🌙"}
31
    </button>
32
  );
33
}

Reading the Current Theme

If you need to read the current theme in a 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(
3
  "data-theme",
4
  shouldBeDark ? "dark" : "light",
5
);

1
// In the useEffect
2
root.setAttribute("data-theme", shouldBeDark ? "dark" : "light");

Then in your CSS:

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