Remix Themes

To persist themes across sessions, you must create a themeSessionResolver using createThemeSessionResolver. This requires a session storage instance (e.g., from createCookieSessionStorage).

Note on Production: Ensure domain and secure parameters are only set for production environments. Setting them on localhost may prevent Safari from storing the cookie.

// sessions.server.tsx
import { createThemeSessionResolver } from "remix-themes";
import { createCookieSessionStorage } from "react-router";

const sessionStorage = createCookieSessionStorage({
  cookie: {
    name: "__remix-themes",
    path: "/",
    httpOnly: true,
    sameSite: "lax",
    secrets: ["s3cr3t"],
  },
});

export const themeSessionResolver = createThemeSessionResolver(sessionStorage);

You must create an action route to handle theme changes. This route is responsible for updating the theme in the session storage. The path provided to ThemeProvider's themeAction prop must match the location of this route.

Example for Route File Naming v2: /routes/action/set-theme.ts or /routes/action.set-theme.ts.

import { createThemeAction } from "remix-themes";
import { themeSessionResolver } from "./sessions.server";

export const action = createThemeAction(themeSessionResolver);

To use remix-themes in your React Router or Remix project, install it via npm or yarn.

$ npm install remix-themes
# or
$ yarn add remix-themes

The createThemeSessionResolver function creates a resolver that bridges your session storage with the theme logic.

Arguments:

• sessionStorage: A session storage instance (e.g., from createCookieSessionStorage).

Returns: An object containing a resolver function. The resolver function accepts a request and returns:

• getTheme: Returns the current theme from session storage.
• setTheme: Sets a new theme name in session storage.
• commit: Commits the session storage and returns the Set-Cookie header.

The PreventFlashOnWrongTheme component prevents a flash of the incorrect theme during hydration when the server-side theme is unknown (null).

If the theme is null on the server, it applies the browser's theme to the <html> element using either a data-theme attribute (preferred) or a class attribute.

Props:

• ssrTheme: A boolean indicating whether a theme was successfully retrieved from the session storage on the server.

The useTheme hook allows you to access and modify the active theme within your components.

Returns: An array containing [theme, setTheme, metadata]:

• theme: The name of the active theme.
• setTheme: A function to update the theme. Passing null sets the theme to the system preference.
• metadata: An object containing:
  • definedBy: The source of the theme ('USER' or 'SYSTEM').

const [theme, setTheme, metadata] = useTheme();

// Example: Set to dark mode
setTheme('dark');

// Example: Revert to system preference
setTheme(null);

The ThemeProvider component manages the theme state and provides the context for theme switching.

Props:

• specifiedTheme: The theme currently stored in the session storage.
• themeAction: The absolute path to the action route used to change the theme.
• disableTransitionOnThemeChange: (Boolean) If true, disables CSS transitions on theme change to prevent flashing effects.

In the react-router.config.ts file, you can control whether the application uses Server-Side Rendering (SSR) or Single Page Application (SPA) mode using the ssr option. By default, ssr is set to true. To enable SPA mode, set ssr to false.

import type { Config } from "@react-router/dev/config";

export default {
  // Config options...
  // Server-side render by default, to enable SPA mode set this to `false`
  ssr: true,
} satisfies Config;

Use createThemeAction to create a Remix/React Router action that handles theme updates. This action typically works in tandem with a ThemeSessionResolver to persist the user's theme preference in their session when they switch themes via a form submission.

import { createThemeAction } from "remix-themes";

// In your route file:
export const action = createThemeAction(themeSessionResolver);