Application Theming System

Guide to implementing theme switching (light/dark) without flicker: Vite — React Context + inline script, Next.js — next-themes.

Theme Management Architecture

Benefit: Isolation of theme logic from business components. Automatic saving of user choice and prevention of theme 'flicker' on load.

Themization File Structure

Location and Conventions

Provider:
Located in src/app/providers/theme/. Responsible for global initialization.
Shared Logic:
Context, hooks, and UI components are placed in shared/ as they are reusable.

01Types and Interfaces

Define allowed theme values (light, dark) and context structure for state management.

shared/ui/layout/theme-toggle/model/theme.types.ts

export type TTheme = "light" | "dark";

export interface IThemeContextType {
    theme: TTheme;
    toggleTheme: () => void;
}

02React Context

Creating a data channel for passing theme data down the component tree without prop drilling.

shared/ui/layout/theme-toggle/model/theme.context.ts

import { createContext } from "react";
import { IThemeContextType } from "./theme.types";

export const ThemeContext = createContext<IThemeContextType | undefined>(undefined);

03Custom Hook

Encapsulating context access logic in a convenient useTheme hook with provider presence validation.

shared/ui/layout/theme-toggle/model/use-theme.ts

import { useContext } from "react";
import { ThemeContext } from "./theme.context";

export const useTheme = () => {
    const context = useContext(ThemeContext);
    if (!context) {
        throw new Error("useTheme must be used within a ThemeProvider");
    }
    return context;
};

04Theme Provider

An inline script in index.html sets the html class before first paint (saved choice or prefers-color-scheme). The provider reads that class as its initial state, follows the system theme until the user picks one, and persists the choice in localStorage. On Next.js use next-themes instead.

index.html

<script>
  (function () {
    try {
      var saved = localStorage.getItem("theme");
      var system = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
      document.documentElement.classList.add(saved === "light" || saved === "dark" ? saved : system);
    } catch (e) {
      document.documentElement.classList.add("light");
    }
  })();
</script>

app/providers/theme/theme.provider.tsx

import { type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
import { type TTheme, ThemeContext } from "@/shared/ui/layout/theme-toggle";

const STORAGE_KEY = "theme";
const DARK_QUERY = "(prefers-color-scheme: dark)";

const getSystemTheme = (): TTheme =>
    window.matchMedia(DARK_QUERY).matches ? "dark" : "light";

/** Класс уже выставлен inline-скриптом до первой отрисовки */
const getInitialTheme = (): TTheme =>
    document.documentElement.classList.contains("dark") ? "dark" : "light";

export const ThemeProvider = ({ children }: { children: ReactNode }) => {
    const [theme, setTheme] = useState<TTheme>(getInitialTheme);

    // Следуем за системной темой, пока нет явного выбора
    useEffect(() => {
        const media = window.matchMedia(DARK_QUERY);
        const onChange = () => {
            if (!localStorage.getItem(STORAGE_KEY)) setTheme(getSystemTheme());
        };
        media.addEventListener("change", onChange);
        return () => media.removeEventListener("change", onChange);
    }, []);

    useEffect(() => {
        const root = document.documentElement;
        root.classList.remove("light", "dark");
        root.classList.add(theme);
    }, [theme]);

    const toggleTheme = useCallback(() => {
        setTheme((prev) => {
            const next = prev === "light" ? "dark" : "light";
            localStorage.setItem(STORAGE_KEY, next);
            return next;
        });
    }, []);

    const value = useMemo(() => ({ theme, toggleTheme }), [theme, toggleTheme]);

    return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
};

// Next.js: вместо своего провайдера — next-themes
// (attribute="class", defaultTheme="system", enableSystem, <html suppressHydrationWarning>)

05Initialization HOC

The withTheme HOC wraps a root component in ThemeProvider, so the theme is connected in one line: export default withTheme(App).

app/providers/theme/with-theme.tsx

import type { ComponentType, FC } from "react";
import { ThemeProvider } from "./theme.provider";

/** Подключение темы одной строкой: export default withTheme(App) */
export const withTheme = <P extends object>(Component: ComponentType<P>): FC<P> => {
    const WithTheme: FC<P> = (props) => (
        <ThemeProvider>
            <Component {...props} />
        </ThemeProvider>
    );

    WithTheme.displayName = `withTheme(${Component.displayName || Component.name || "Component"})`;

    return WithTheme;
};

06UI Component (Toggle)

Creating a toggle button that uses the useTheme hook to switch the visual state.

shared/ui/layout/theme-toggle/ui/theme-toggle.tsx

import { Moon, Sun } from "lucide-react";
import { Button } from "@/shared/ui";
import { useTheme } from "../model";

export const ThemeToggle = () => {
    const { theme, toggleTheme } = useTheme();

    return (
        <Button onClick={toggleTheme} variant="outline" size="sm">
            {theme === "light" ? <Moon size={16} /> : <Sun size={16} />}
        </Button>
    );
};