Docs: Improve error message and docs for mixing Storybook and React hooks in render functions

[Copilot]

Using Storybook hooks (e.g. useArgs) alongside React hooks (useState, useEffect, useRef) in the same render function causes a cryptic error on re-render — React re-renders don't run through Storybook's hook context, so Storybook hooks fail.

Changes

• Better error message (preview-api/modules/addons/hooks.ts): Extended the existing error to explain the root cause and point directly to the fix — use Storybook's equivalents from storybook/preview-api instead of React's hooks.

• Warning callout in args.mdx: Added after the useArgs code example explaining the constraint, listing the available Storybook hook equivalents, and showing correct usage:

  // ✅ Import all hooks from storybook/preview-api when using useArgs
  import { useArgs, useState, useEffect } from 'storybook/preview-api';
  
  export const MyStory = {
    render: function Render(args) {
      const [{ value }, updateArgs] = useArgs();
      const [localState, setLocalState] = useState(false);
      useEffect(() => { /* ... */ }, [value]);
      return <MyComponent {...args} />;
    },
  };

• Updated decorators.mdx: Improved the hooks context property description to mention the re-render constraint and point to storybook/preview-api equivalents.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug]: using both React and Storybook hooks in the same render function causes Storybook preview hooks can only be called inside decorators and story functions.</issue_title>
<issue_description>### Describe the bug

see reproduction and title.

Things of note:

• I think this is a reproduction of [Bug]: Storybook preview hooks can only be called inside decorators and story functions. #29189 (comment) .The original issue was closed with the instruction to create a new story with a reproduction, so here I am.
• This seemed to work fine in storybook 8.6.15
• First render is fine, it's only on re-render triggered by react (e.g. by the setter from useState) that it seems to fail
• This seems to happen with any combination of hooks (useRef was the one which triggered it for me initially, although I only realised that after writing most of this issue!)
• If this is intended behavior then the message and documentation need to make it clear that this can cause problems because I can't find anything that would point to this being necessary.

Reproduction link

https://stackblitz.com/edit/github-5wmurpp9-g1s8rwx1?file=src%2Fstories%2Freproduction.stories.tsx&preset=node

Reproduction steps

1. Load stackblitz reproduction url
2. choose one of the "Breaks" stories
3. Click the Click to break button

System

│
│
│  Storybook Environment Info:
│

│  System:
│  OS: Windows 11 10.0.26200
│  CPU: (24) x64 AMD Ryzen 9 5900X 12-Core Processor
│  Binaries:
│  Node: 22.20.0 - C:\nvm4w\nodejs\node.EXE
│  npm: 10.9.3 - C:\nvm4w\nodejs\npm.CMD <----- active
│  Browsers:
│  Chrome: 144.0.7559.133
│  npmPackages:
│  @storybook/react-vite: ^10.2.4 => 10.2.4
│  eslint-plugin-storybook: ^10.2.4 => 10.2.4
│  storybook: ^10.2.4 => 10.2.4

Additional context

No response</issue_description>

<agent_instructions>I think we should clarify this in our documentation, by not just adding a clarification sentence, but actually by providing good examples about how to extend the render function to use useState, useArgs, useEffect from storybook/preview-api, and real-world use-cases and examples. Additionally, we should provide a more concise error message to ensure our users can resolve the issue themselves.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@valentinpalkovic Hi @jetwiwo

Thank you for creating the issue and thank you so much for the detailed reproduction.

Indeed, this is an issue of poor communication and incomplete documentation. The render function should only be called with hooks, which the storybook/preview-api provides, and should not be called with render hooks like useState or useEffect from React.

@jonniebigodes I think we should clarify this in our documentation, by not just adding a clarification sentence, but actually by providing good examples about how to extend the render function to use useState, useArgs, useEffect from storybook/preview-api, and real-world use-cases and examples. Additionally, we should provide a more concise error message to ensure our users can resolve the issue themselves.</comment_new>
<comment_new>@jonniebigodes
@valentinpalkovic I agree with your suggestion. In all honesty, that section of the documentation was introduced a while ago by an external contributor and has since been left unmaintained, with only minimal testing. I'll take a look into it and adjust it when I'm able.</comment_new>

• Fixes [Bug]: using both React and Storybook hooks in the same render function causes Storybook preview hooks can only be called inside decorators and story functions. #33804

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Summary by CodeRabbit

• Documentation

  • Clarified that useArgs and useGlobals are available in stories and decorators.
  • Added a warning about mixing Storybook hooks with framework hooks and guidance to prefer Storybook's preview-api hook equivalents to avoid re-render issues.

• Improvements

  • Enhanced error message with clearer, multi-line guidance when hooks are used incorrectly.

[github-actions]

	Fails
🚫	PR description is missing the mandatory "#### Manual testing" section. Please add it so that reviewers know how to manually test your changes.

Generated by 🚫 dangerJS against 2dd18d2

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 2dd18d2

Command	Status	Duration	Result
nx run-many -t compile,check,knip,test,pretty-d...	❌ Failed	6m 20s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-02-27 15:31:27 UTC

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0c5405e and 4bf2e5b.

📒 Files selected for processing (1)

• docs/writing-stories/args.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/writing-stories/args.mdx

---

📝 Walkthrough

Walkthrough

Enhanced an internal hook error message and updated docs to warn against mixing Storybook preview hooks with framework hooks, recommending Storybook's preview-api hook equivalents; no public API or runtime control-flow changes.

Changes

Cohort / File(s)	Summary
Hook Error Messaging code/core/src/preview-api/modules/addons/hooks.ts	Expanded invalidHooksError message to a multi-line error that advises not to mix Storybook preview hooks with framework hooks and recommends using hooks from storybook/preview-api.
Documentation Updates docs/writing-stories/args.mdx, docs/writing-stories/decorators.mdx	Added warning callouts and clarified that useArgs and useGlobals are available in decorators and story renders; advise using Storybook preview-api hook equivalents to avoid re-render/context issues and include usage guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[storybook-app-bot]

Package Benchmarks

^{Commit: 2dd18d2, ran on 27 February 2026 at 15:36:24 UTC}

No significant changes detected, all good. 👏

[jonniebigodes]

This is looking great. I just tweaked the messaging a bit and will get it in once the checklist clears.