Storybook preview iframe and React Query suspense mode interoperability

Answer

Yes – the Storybook 8.x preview iframe will render the Suspense fallback defined in your story (or via a decorator) when a story uses useQuery({ suspense: true }) and the query promise is still pending, provided a <Suspense> boundary exists above the component that calls the hook.

Confirmed facts

• The preview iframe is a standard React root; it does not block or swallow Suspense boundaries.
• React Query’s suspense: true (or useSuspenseQuery) throws a promise that is caught by the nearest <Suspense> in the tree.
• If no <Suspense> boundary wraps the story, the suspended promise bubbles to the root, resulting in a blank preview or an error overlay.

Steps to verify the fallback appears

1. Wrap your stories (globally or per‑story) with a decorator that provides both <QueryClientProvider> and <Suspense fallback={}>.
2. In the story, render the component that calls useQuery({ suspense: true }).
3. Mock the API delay (e.g., with MSW) so the initial promise stays pending for a few seconds.
4. Open the Storybook preview iframe and inspect the DOM; you should see the fallback element rendered while the promise is pending.
5. When the mock resolves, the fallback should be replaced by the actual data.

Missing diagnostic detail

Are you currently wrapping your story with a <Suspense> boundary (either directly in the story file or via a global decorator)? Knowing this determines whether you need to add the boundary or if another issue is causing a blank preview.