{"record":{"id":"b5e68dcd795c6f4b","repo":"facebook/docusaurus","slug":"hook-is-called-outside-the-colormodeprovider-pl","errorCode":null,"errorMessage":"Hook is called outside the <ColorModeProvider>. Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.","messagePattern":"Hook is called outside the <ColorModeProvider>\\. Please see https://docusaurus\\.io/docs/api/themes/configuration#use-color-mode\\.","errorType":"exception","errorClass":"ReactContextError","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-theme-common/src/contexts/colorMode.tsx","lineNumber":251,"sourceCode":"      setColorMode,\n    }),\n    [colorMode, colorModeChoice, setColorMode],\n  );\n}\n\nexport function ColorModeProvider({\n  children,\n}: {\n  children: ReactNode;\n}): ReactNode {\n  const value = useContextValue();\n  return <Context.Provider value={value}>{children}</Context.Provider>;\n}\n\nexport function useColorMode(): ContextValue {\n  const context = useContext(Context);\n  if (context == null) {\n    throw new ReactContextError(\n      'ColorModeProvider',\n      'Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.',\n    );\n  }\n  return context;\n}\n","sourceCodeStart":233,"sourceCodeEnd":258,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-theme-common/src/contexts/colorMode.tsx#L233-L258","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Wrap any isolated/test render of consuming components with `<ColorModeProvider>` (and a mock context value if needed).","Confirm your swizzled root layout still mounts `<ColorModeProvider>` as an ancestor of the toggle.","If hitting this in Storybook, add a decorator that provides the context.","Read the linked docs page (https://docusaurus.io/docs/api/themes/configuration#use-color-mode) for the expected setup."],"exampleFix":"// before — test renders the toggle without provider\nrender(<MyToggle />); // throws\n// after\nimport {ColorModeProvider} from '@docusaurus/theme-common/internal';\nrender(<ColorModeProvider><MyToggle /></ColorModeProvider>);","handlingStrategy":"validation","validationCode":"import {useContext} from 'react';\nimport {Context} from '@docusaurus/theme-common/internal/colorMode';\nfunction useColorModeSafe() {\n  const ctx = useContext(Context);\n  return ctx ?? null;\n}","typeGuard":null,"tryCatchPattern":"try {\n  const {colorMode, setColorMode} = useColorMode();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('ColorModeProvider')) return null;\n  throw e;\n}","preventionTips":["Wrap test/Storybook renders of consumers with `<ColorModeProvider>`.","Keep the provider in the swizzled root layout.","Read the linked docs page for the canonical setup."],"tags":["react","context","color-mode","theme-common","testing"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}