Application Theming System

Guide to implementing theme switching (light/dark) using React Context, HOC, and localStorage.

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/useTheme.tsx

import { useContext } from "react";
import { ThemeContext } from "../context/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

Implementing a provider component that manages state, interacts with localStorage, and manipulates html classes.

app/providers/theme/theme.provider.tsx

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

export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
    const [theme, setTheme] = useState<TTheme>("light");
    const [mounted, setMounted] = useState(false);

    useEffect(() => {
        const saved = localStorage.getItem("theme") as TTheme;
        if (saved) setTheme(saved);
        setMounted(true);
    }, []);

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

    useEffect(() => {
        if (!mounted) return;
        document.documentElement.classList.remove("light", "dark");
        document.documentElement.classList.add(theme);
    }, [theme, mounted]);

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

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

05Initialization HOC

Creating the withTheme Higher-Order Component for easy application wrapping at the provider level.

app/providers/theme/with-theme.tsx

import React from "react";
import { ThemeProvider } from "./theme.provider";

export const withTheme = <P extends object>(Component: React.ComponentType<P>) => {
    return (props: P) => (
        <ThemeProvider>
            <Component {...props} />
        </ThemeProvider>
    );
};

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>
    );
};