{"record":{"id":"7caa34770231860c","repo":"remotion-dev/remotion","slug":"usecurrentframe-can-only-be-called-inside-a-compon","errorCode":null,"errorMessage":"useCurrentFrame can only be called inside a component that was passed to <Player>. See: https://www.remotion.dev/docs/player/examples","messagePattern":"useCurrentFrame can only be called inside a component that was passed to <Player>\\. See: https://www\\.remotion\\.dev/docs/player/examples","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/use-current-frame.ts","lineNumber":17,"sourceCode":"import {useContext} from 'react';\nimport {CanUseRemotionHooks} from './CanUseRemotionHooks.js';\nimport {SequenceContext} from './SequenceContext.js';\nimport {useTimelinePosition} from './timeline-position-state.js';\nimport {useRemotionEnvironment} from './use-remotion-environment.js';\n\n/*\n * @description Retrieves the current frame of the video within a component. Frames are 0-indexed, and if the component is wrapped in a `<Sequence>`, it returns the frame relative to when the Sequence starts.\n * @see [Documentation](https://www.remotion.dev/docs/use-current-frame)\n */\nexport const useCurrentFrame = (): number => {\n\tconst canUseRemotionHooks = useContext(CanUseRemotionHooks);\n\tconst env = useRemotionEnvironment();\n\n\tif (!canUseRemotionHooks) {\n\t\tif (env.isPlayer) {\n\t\t\tthrow new Error(\n\t\t\t\t`useCurrentFrame can only be called inside a component that was passed to <Player>. See: https://www.remotion.dev/docs/player/examples`,\n\t\t\t);\n\t\t}\n\n\t\tthrow new Error(\n\t\t\t`useCurrentFrame() can only be called inside a component that was registered as a composition. See https://www.remotion.dev/docs/the-fundamentals#defining-compositions`,\n\t\t);\n\t}\n\n\tconst frame = useTimelinePosition();\n\tconst context = useContext(SequenceContext);\n\n\tconst contextOffset = context\n\t\t? context.cumulatedFrom + context.relativeFrom\n\t\t: 0;\n\n\treturn frame - contextOffset;\n};","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/core/src/use-current-frame.ts#L1-L35","documentation":"useCurrentFrame() checks the CanUseRemotionHooks context before reading the timeline. When the hook is called outside a Remotion render tree and the environment is the Player, this specific message fires, telling you the calling component is not the one passed to <Player>.","triggerScenarios":"Calling useCurrentFrame() in a component that is rendered outside the <Player component={...}> tree, e.g. as a sibling of <Player>, in a parent that wraps <Player>, or in a controls overlay that is not a child of the Player's component prop.","commonSituations":"Building custom Player controls or chrome that lives outside the composition component; calling useCurrentFrame() in a hook used by both Player controls and the composition; SSR or preview renders.","solutions":["Move the useCurrentFrame() call into the component passed to <Player component={...}>.","Pass the current frame from the Player via the component prop tree instead of reading it in an outer wrapper.","Use the Player's onFrame prop or a ref-based subscription to observe the frame outside the composition."],"exampleFix":"// before\nfunction App() {\n  const frame = useCurrentFrame();\n  return (\n    <>\n      <FrameLabel frame={frame} />\n      <Player component={Video} {...props} />\n    </>\n  );\n}\n\n// after\nfunction Video() {\n  const frame = useCurrentFrame();\n  return <FrameLabel frame={frame} />;\n}\nfunction App() {\n  return <Player component={Video} {...props} />;\n}","handlingStrategy":"validation","validationCode":"// Move the hook into the component passed to <Player component={...}/>\nfunction CompositionComponent() {\n  const frame = useCurrentFrame();\n  return <Overlay frame={frame} />;\n}\n\n<Player component={CompositionComponent} {...playerProps} />","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Call useCurrentFrame() only inside the component prop of <Player>/<Composition>.","Build Player chrome (controls, overlays outside the composition) without Remotion hooks; subscribe to the Player ref instead.","Keep composition components in their own files to discourage reuse in non-Player trees."],"tags":["react","context","hook","player","use-current-frame"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}