facebook/docusaurus · error · Error

usePlayground must be used within PlaygroundProvider

Error message

usePlayground must be used within PlaygroundProvider

What it means

usePlayground() consumes PlaygroundContext, which is populated only by PlaygroundProvider (used by the live-codeblock Playground component). Calling the hook where useContext returns null throws 'usePlayground must be used within PlaygroundProvider'. This is the standard missing-provider guard for the live-codeblock plugin.

Source

Thrown at packages/docusaurus-theme-live-codeblock/src/client/context.tsx:33

export function PlaygroundProvider({
  value,
  children,
}: {
  value: PlaygroundContextValue;
  children: ReactNode;
}): ReactNode {
  return (
    <PlaygroundContext.Provider value={value}>
      {children}
    </PlaygroundContext.Provider>
  );
}

export function usePlayground(): PlaygroundContextValue {
  const context = useContext(PlaygroundContext);
  if (!context) {
    throw new Error('usePlayground must be used within PlaygroundProvider');
  }
  return context;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Only call usePlayground() inside components rendered by <Playground> (which provides PlaygroundProvider).
2. In custom theme code, wrap the consumer in <PlaygroundProvider value={{reset}}>, or re-mount the full Playground.
3. In tests, render the consumer inside a PlaygroundProvider with a stub value.

Example fix

// before
function ResetButton() {
  const {reset} = usePlayground(); // used outside Playground
  return <button onClick={reset}>Reset</button>;
}
<ResetButton />
// after
<Playground ...>
  <ResetButton />
</Playground>

When it happens

Trigger: Call usePlayground() from a component that is not a descendant of the Playground component (which renders PlaygroundProvider); swizzle a Playground subcomponent and render it independently; use the hook in a test without the provider.

Common situations: Customizing @theme/Playground or its children and moving a consumer out of the provider subtree; reusing playground subcomponents elsewhere in the site; unit tests of playground internals.

Related errors

• useTabsContext() must be used within a Tabs component
• Hook is called outside the <AnnouncementBarProvider>.
• Hook is called outside the <ColorModeProvider>. Please see h
• Hook is called outside the <NavbarMobileSidebarProvider>.
• Hook is called outside the <NavbarSecondaryMenuContentProvid

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