Toggle Themes in React with Chakra UI’s useColorMode Hook

What You’ll Get

Chakra UI’s useColorMode hook instantly gives you a light/dark toggle that persists across page loads. The hook returns the current mode and a function to switch it, relying on ChakraProvider’s colorModeManager (defaulting to localStorage). Below you’ll see how to wire it up, what to watch for, and how to avoid the most common mistakes.

How useColorMode Works

When you wrap your app in <ChakraProvider>, Chakra creates a React context that holds theme data. useColorMode consumes that context and returns a two‑element array: the current color mode string ("light" or "dark") and a toggleColorMode function. Internally, the hook calls the provider’s colorModeManager to read/write the mode value, so the choice survives page refreshes. If useSystemColorMode is enabled in the provider’s theme config, the hook will sync with the OS preference on initial mount.

Example Setup

1. Install Chakra UI

2. npm i @chakra-ui/react @emotion/react @emotion/styled framer-motion

3. Create a theme config

4. import { extendTheme } from "@chakra-ui/react";
   
   const theme = extendTheme({
     config: {
       initialColorMode: "light", // default when no stored value
       useSystemColorMode: false,   // set to true to follow OS
     },
   });
   
   export default theme;

5. Wrap the app

6. import { ChakraProvider } from "@chakra-ui/react";
   import theme from "./theme";
   
   function App() {
     return (
       
         
       
     );
   }
   
   export default App;

7. Use the hook in a component

8. import { Button, useColorMode } from "@chakra-ui/react";
   
   export function ThemeSwitcher() {
     const { colorMode, toggleColorMode } = useColorMode();
   
     return (
       
         Switch to {colorMode === "light" ? "dark" : "light"} mode
       
     );
   }

When you click the button, toggleColorMode flips the mode, updates localStorage under the key chakra-ui-color-mode, and Chakra re‑renders components with the new theme values.

Checking the Result

• Open the browser console and inspect localStorage for the key chakra-ui-color-mode.
• Reload the page; the button should reflect the stored mode and the UI should match.
• In the UI, verify that color tokens (e.g., bg, color) switch between the light and dark palettes defined in your theme.

Common Mistakes & How to Avoid Them

• Calling useColorMode outside ChakraProvider
  Result: "Error: useColorMode must be used within a ChakraProvider". Always wrap the component tree with <ChakraProvider> before using the hook.
• Server‑Side Rendering (SSR) without a manager
  SSR renders the page with the default mode, then the client hydrates with the stored mode, causing a flash of the wrong theme. Provide a custom colorModeManager that works on the server (e.g., cookie‑based) or disable useSystemColorMode during SSR.
• Ignoring the initialColorMode config
  If you want a hard‑coded default (e.g., dark on first load regardless of localStorage), set initialColorMode in the theme config and clear any existing key from localStorage.
• Using localStorage directly
  Manipulating the storage key manually can desynchronize Chakra’s internal state. Let Chakra handle persistence.

Limitations

• The default colorModeManager uses localStorage, which is not available in SSR environments or certain browsers in incognito mode.
• Switching themes triggers a full re‑render of all Chakra components that read color tokens, which may impact performance in very large UIs.
• Custom color palettes must be defined for both modes; otherwise components may fall back to defaults and look inconsistent.

Practical Checklist

1. Wrap the root component with <ChakraProvider> and pass a theme with a config object.
2. Use useColorMode inside components that need to read or change the mode.
3. Verify localStorage persists the key after toggling.
4. For SSR, provide a server‑compatible colorModeManager or disable system sync during initial render.
5. Test the toggle on browsers that block localStorage to ensure graceful degradation.

Conclusion

Chakra UI’s useColorMode hook offers a clean, declarative way to implement theme toggling. By correctly configuring ChakraProvider, handling SSR nuances, and avoiding the common pitfalls listed above, you can give users a consistent light/dark experience that’s remembered across sessions.