next.js: useSearchParams() should not need to be wrapped in a suspense boundary
Link to the code that reproduces this issue
https://codesandbox.io/p/devbox/nameless-cookies-go8s7s
To Reproduce
- Write a page that calls
useSearchParamsfromnext/navigation - Make it a client component by adding “use client” at the top
- run
npm run build - observe error
useSearchParams() should be wrapped in a suspense boundary at page "/test". Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout
Current vs. Expected behavior
- The documentation associated with this error is no longer accurate- the linked page suggests to disable the error by adding the experimental feature
missingSuspenseWithCSRBailoutto next.config.js. This option does not work, and will cause the build to error out saying that feature/flag doesn’t exist. - I don’t see why
useSearchParamsis any different WRT suspense than any other client function like useState. I don’t need suspense for them, and I don’t see why I should need suspense foruseSearchParams - This is not a problem in development- it neither gives an error nor has incorrect behavior.
Provide environment information
Operating System:
Platform: darwin
Arch: arm64
Version: Darwin Kernel Version 24.1.0: Thu Oct 10 21:02:26 PDT 2024; root:xnu-11215.41.3~2/RELEASE_ARM64_T8122
Available memory (MB): 16384
Available CPU cores: 8
Binaries:
Node: 20.17.0
npm: 10.8.2
Yarn: 1.22.22
pnpm: 9.15.0
Relevant Packages:
next: 15.1.3 // Latest available version is detected (15.1.3).
eslint-config-next: 15.1.3
react: 19.0.0
react-dom: 19.0.0
typescript: 5.7.2
Next.js Config:
output: N/A
Which area(s) are affected? (Select all that apply)
Not sure, Documentation
Which stage(s) are affected? (Select all that apply)
next build (local)
Additional context
The linked codesandbox is on the latest canary, and the issue still appears.
About this issue
- Original URL
- State: open
- Created 2 years ago
- Reactions: 7
- Comments: 16 (5 by maintainers)
And, sorry but I just ran into this constraint again, why does it complain about a Suspense boundary for a component that is marked with ‘use client’, as in it will get rendered client side anyway?
Also while it’s clear that static pages can’t be generated while using
useSearchParams, it doesn’t make any sense why we can not have normal Server Side Rendering with search params. The params 100% get delivered to the server with the request and it can just render the page, nothing prevents it except the current implementation. Forcing client-side rendering doesn’t make sense at all.In my case our website uses query parameter ?lang=en to switch languages so we would need to wrap our whole website in Suspense. So SSR not possible with Next.js, basically.
I would like to join this discussion because I am encountering this error on a page that is marked as
'use client'. Referring to the documentation, there is no opt-in. The page is marked as a client-rendered page.Thus, my only option is to disable this check, I think because it is being triggered even though I know that my whole page is client-side rendered.
Further, what other option do I have on an app that is using the
exportoutput type to pass a search parameter to another page, for example? Only other thing that comes to mind is local/session storage, which feels ‘odd’.Any hints how to implement it correctly? Thank you!
Should be a prop you could pass into useSearchParams to have it return empty arrays and null for values during the server pass.
Even the type of searchParams.get() contains null, so we’re already forced to handle this case.
Update! It took me longer than I’d like to admit, but eventually tunneled the issue into being our Navbar on the layout level which needed to be wrapped in a suspense as it had useSearchParams() used within it.
Didn’t realize that would break all the pages with that, but now is working as intended.
me too i am having the same issue…even after wrapping my component with <Suspense>. …i am just about to downgrade back to nextjs 14…nextjs 15 might not yet be that so stable …i just like the react compiler as it optimizes my animations
No worries, it is important to refine the concepts and arguments, perhaps after all, more documentation is needed, who knows.
I personally, try to avoid using
useSearchParamsunless, my component does actually need to render, based off the search params, but I see that it is common, for devs to invoke the hook, to then use the values returned within an event listener, or within an effect, that doesn’t depend on the value, but needs it, tracking is often the case.window.location.searchdoes the trick in those cases.This is but a matter of pre-rendering, vs on-demand.
next buildruns in your build environment, and has no request, no server, nada, so the concept of search params, and other elements otherwise present in a request, are a non-starter.useSearchParams, on a dynamic (on-demand) route, would work just fine, https://nextjs.org/docs/app/api-reference/functions/use-search-params#dynamic-rendering:I guess the tricky thing is that,
searchParamsat page level, opts into dynamic rendering, implicitly, whereasuseSearchParams, keeps static rendering open, at the cost of"suspending"to the client.An alternative would be the pages router approach, give an empty container, hydrate with the empty container, and immediately, without letting the browser paint, re-render with a “filled” container, but that had also a bunch of caveats, https://nextjs.org/docs/pages/building-your-application/rendering/automatic-static-optimization#how-it-works, and I recall people running into problems as well.