Suspense doesn't work for <Link/>

[wangwalton]

Link to the code that reproduces this issue

https://github.com/wangwalton/nextjs-bug

To Reproduce

1. navigate to locahost:3000/
2. click any of those links
3. observe suspense fallback does not occur

Current vs. Expected behavior

Current: suspense fallback not showing
Exepected: suspense fallback used

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.4.0: Fri Mar 15 00:12:41 PDT 2024; root:xnu-10063.101.17~1/RELEASE_ARM64_T8103
  Available memory (MB): 16384
  Available CPU cores: 8
Binaries:
  Node: 21.7.1
  npm: 10.5.0
  Yarn: 1.22.22
  pnpm: 9.10.0
Relevant Packages:
  next: 15.3.0 // Latest available version is detected (15.3.0).
  eslint-config-next: 15.3.0
  react: 19.1.0
  react-dom: 19.1.0
  typescript: 5.8.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Linking and Navigating

Which stage(s) are affected? (Select all that apply)

next dev (local)

Additional context

No response

[icyJoseph]

There are no links in the provided repository.

[bduff9]

There are no links in the provided repository.

Actually, there are several, they are just in the layout file not the page.

[icyJoseph]

Strange, I ran this earlier and I only saw Page for index: none, maybe I accidentally removed the layout 😅 Not sure how though, https://stackblitz.com/github/wangwalton/nextjs-bug?file=src%2Fapp%2Fpage.tsx I ran it on a Stackblitz ~ anyway, looking into this

[icyJoseph]

Ok, so this is like a known issue... Suspense boundaries persist, so if one already triggered, it won't trigger again, one common trick is to do:

import { Suspense } from 'react';

export default async function PageWrapper({
  searchParams,
}: {
  searchParams: Promise<{ index?: string }>;
}) {
  const search = await searchParams;
  const key = new URLSearchParams(search).toString();
  return (
    <Suspense key={key} fallback={<div>⏳ Suspense Fallback...</div>}>
      <Page searchParams={search} />
    </Suspense>
  );
}

async function Page({ searchParams }: { searchParams: { index?: string } }) {
  await new Promise((resolve) => setTimeout(resolve, 1500));
  return <h1>Page for index: {searchParams.index ?? 'none'}</h1>;
}

I'll post more x-ref links in a minute.

• Working example: https://stackblitz.com/edit/github-fce5befp?file=src%2Fapp%2Fpage.tsx using OPs submission
• Updating search params does not trigger suspense fallback or loading.tsx #53543 (comment)
• Suspense only shows its fallback once (on page load), when async component suspends, the Suspense wrapper doesn't fall back. All components working however #50563

So, by changing the key passed to the boundary, we recreate that instance, https://react.dev/learn/preserving-and-resetting-state#option-2-resetting-state-with-a-key

[wangwalton]

works great 👍 👍 👍 thanks so much!

[icyJoseph]

The React docs do have an entry about this, I had missed it, https://react.dev/reference/react/Suspense#resetting-suspense-boundaries-on-navigation

Please don't forget to close if you are satisfied.