facebook/docusaurus · error · ReactContextError

Hook is called outside the <ColorModeProvider>. Please see h

Error message

Hook is called outside the <ColorModeProvider>. Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.

What it means

Thrown by `useColorMode()` when its React context is `null`, meaning the hook ran outside `<ColorModeProvider>`. This is the most common 'hook outside provider' error in Docusaurus because `useColorMode` is frequently called from user components (e.g. custom theme toggle widgets) that get rendered outside the theme's provider tree.

Source

Thrown at packages/docusaurus-theme-common/src/contexts/colorMode.tsx:251

      setColorMode,
    }),
    [colorMode, colorModeChoice, setColorMode],
  );
}

export function ColorModeProvider({
  children,
}: {
  children: ReactNode;
}): ReactNode {
  const value = useContextValue();
  return <Context.Provider value={value}>{children}</Context.Provider>;
}

export function useColorMode(): ContextValue {
  const context = useContext(Context);
  if (context == null) {
    throw new ReactContextError(
      'ColorModeProvider',
      'Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.',
    );
  }
  return context;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Wrap any isolated/test render of consuming components with `<ColorModeProvider>` (and a mock context value if needed).
2. Confirm your swizzled root layout still mounts `<ColorModeProvider>` as an ancestor of the toggle.
3. If hitting this in Storybook, add a decorator that provides the context.
4. Read the linked docs page (https://docusaurus.io/docs/api/themes/configuration#use-color-mode) for the expected setup.

Example fix

// before — test renders the toggle without provider
render(<MyToggle />); // throws
// after
import {ColorModeProvider} from '@docusaurus/theme-common/internal';
render(<ColorModeProvider><MyToggle /></ColorModeProvider>);

import {useContext} from 'react';
import {Context} from '@docusaurus/theme-common/internal/colorMode';
function useColorModeSafe() {
  const ctx = useContext(Context);
  return ctx ?? null;
}

try {
  const {colorMode, setColorMode} = useColorMode();
} catch (e) {
  if (e instanceof Error && e.message.includes('ColorModeProvider')) return null;
  throw e;
}

When it happens

Trigger: A component calls `useColorMode()` but is rendered outside the provider — e.g. inside a custom React root, a portal outside the layout, an isolated component preview, or a Storybook/MDX playground that does not set up the Docusaurus theme providers.

Common situations: Using `useColorMode` in a component tested in isolation (Jest/RTL without `ColorModeProvider` wrapper); a Storybook story missing the provider decorator; a swizzled layout that dropped `<ColorModeProvider>`; rendering a custom toggle inside a portal that escapes the provider.

Related errors

• Hook is called outside the <AnnouncementBarProvider>.
• Hook is called outside the <NavbarMobileSidebarProvider>.
• Hook is called outside the <NavbarSecondaryMenuContentProvid
• Hook is called outside the <NavbarSecondaryMenuDisplayProvid
• Hook is called outside the <CodeBlockContextProvider>.

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/b5e68dcd795c6f4b. Report an issue: GitHub.