{"record":{"id":"0a610bbf2ff0ef93","repo":"remotion-dev/remotion","slug":"usepixeldensity-was-called-outside-of-a-remotion","errorCode":null,"errorMessage":"usePixelDensity() was called outside of a Remotion context.\nThis hook can only be called in a component that is being rendered by Remotion.\nIf you want this hook to return the browser pixel density outside of Remotion, pass {dontThrowIfOutsideOfRemotion: true} as an option.\nIf you think you called this hook in a Remotion component, make sure all versions of Remotion are aligned.","messagePattern":"usePixelDensity\\(\\) was called outside of a Remotion context\\.\nThis hook can only be called in a component that is being rendered by Remotion\\.\nIf you want this hook to return the browser pixel density outside of Remotion, pass (.+?) as an option\\.\nIf you think you called this hook in a Remotion component, make sure all versions of Remotion are aligned\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/use-pixel-density.ts","lineNumber":34,"sourceCode":"};\n\n/*\n * @description Retrieves the current pixel density. In previews, this corresponds to `window.devicePixelRatio`. During renders, this corresponds to the `scale` option.\n * @see [Documentation](https://www.remotion.dev/docs/use-pixel-density)\n */\nexport const usePixelDensity = (options?: Options): number => {\n\tconst pixelDensity = useContext(PixelDensityContext);\n\tconst canUseRemotionHooks = useContext(CanUseRemotionHooks);\n\n\tif (pixelDensity !== null) {\n\t\treturn pixelDensity;\n\t}\n\n\tif (canUseRemotionHooks || options?.dontThrowIfOutsideOfRemotion) {\n\t\treturn getBrowserPixelDensity();\n\t}\n\n\tthrow new Error(\n\t\t[\n\t\t\t'usePixelDensity() was called outside of a Remotion context.',\n\t\t\t'This hook can only be called in a component that is being rendered by Remotion.',\n\t\t\t'If you want this hook to return the browser pixel density outside of Remotion, pass {dontThrowIfOutsideOfRemotion: true} as an option.',\n\t\t\t'If you think you called this hook in a Remotion component, make sure all versions of Remotion are aligned.',\n\t\t].join('\\n'),\n\t);\n};\n","sourceCodeStart":16,"sourceCodeEnd":43,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/core/src/use-pixel-density.ts#L16-L43","documentation":"usePixelDensity throws when there is no PixelDensityContext value AND the CanUseRemotionHooks flag is false (i.e. the component is not inside a Remotion render tree) and the caller did not opt into {dontThrowIfOutsideOfRemotion: true}. It protects against calling the hook in plain React/browser code where no Remotion provider is mounted.","triggerScenarios":"Calling usePixelDensity() in a component rendered outside <RemotionRoot>/<Composition>/Player; calling it during SSR with no context; calling it in a Storybook or standalone demo without Remotion providers; calling it in a Node script.","commonSituations":"Sharing a component between a Remotion video and a regular React app; unit-testing a component that calls usePixelDensity without the provider; extracting a sub-component into a library used outside Remotion.","solutions":["Only call usePixelDensity inside components rendered by Remotion (Composition/Player).","If you need the value outside Remotion, call usePixelDensity({dontThrowIfOutsideOfRemotion: true}) to fall back to window.devicePixelRatio.","Wrap your test/demo tree in the Remotion providers so the context is populated.","Split the component: a Remotion-specific version using the hook and a plain version for non-Remotion use."],"exampleFix":"// before\nconst dpr = usePixelDensity();\n\n// after (outside Remotion)\nconst dpr = usePixelDensity({dontThrowIfOutsideOfRemotion: true});","handlingStrategy":"validation","validationCode":"// If the component may render outside Remotion:\nconst dpr = usePixelDensity({ dontThrowIfOutsideOfRemotion: true });","typeGuard":null,"tryCatchPattern":"// Wrap usage so non-Remotion contexts degrade gracefully\nfunction safePixelDensity() {\n  try {\n    return usePixelDensity();\n  } catch {\n    return typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;\n  }\n}","preventionTips":["Reserve usePixelDensity for components rendered by Remotion; pass dontThrowIfOutsideOfRemotion when sharing code with non-Remotion apps.","Split shared components into Remotion and non-Remotion variants.","In tests, wrap the tree in Remotion providers before rendering."],"tags":["remotion","context","pixel-density","hooks"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}