[Bug]: next-themes forces stale theme when Next.js cacheComponents/Activity is enabled (React 19, Next 16)

[juancarloselorriaga]

What happened?

Summary

When using next-themes 0.4.6 with Next.js 16 (cacheComponents: true) + React 19, switching locales causes a hidden ThemeProvider to reapply its stale theme when it becomes
active again. The UI and localStorage end up out of sync and the theme flips back to the previous value.

Environment

• next-themes: 0.4.6
• Next.js: 16.0.3 (App Router)
• React: 19.2.0
• cacheComponents: true (Activity enabled)
• next-intl: 4.5.3
• Tailwind: 4.1.x

Repro steps

1. In next.config.ts, set cacheComponents: true.
2. Wrap the app with ThemeProvider from next-themes in a Providers component (standard setup: attribute="class", storageKey="my-theme", defaultTheme="system",
   enableSystem, enableColorScheme).
3. Route structure with locales: app/[locale]/layout.tsx, app/[locale]/page.tsx (or any content).
4. Use any two locales (e.g., en, es) via next-intl or similar.
5. Run dev server, open /en.
6. Sequence:
   • Toggle theme to Dark.
   • Switch locale to ES.
   • Toggle theme to Light.
   • Switch locale back to EN.
7. Observe: theme flips back to Dark (the stale value). localStorage may show Light, but the DOM class flips to the older value when the hidden tree is reactivated.

Expected

The theme should remain at the last user selection (Light after the sequence), with DOM class and localStorage in sync.

Actual

When returning to the previous locale, the hidden ThemeProvider instance preserved by Activity (cacheComponents) re-applies its stale theme, flipping the UI. Multiple
ThemeProviders appear to mount/unmount; their effects each write to storage/DOM, causing oscillation.

Notes / Hypothesis

• React 19 + Next 16 Activity keeps previous route trees “hidden” instead of unmounted. next-themes assumes a single live provider; hidden instances still run effects and
  write the theme (DOM class + storage) when they become active again.
• With cacheComponents disabled (so Activity is off), the bug disappears.
• A custom single-writer theme manager that applies the class directly and listens to storage events fixes the issue.
• Mitigations could be:
  • Make next-themes Activity-aware (single-writer or guard DOM/storage writes when hidden).
  • Key ThemeProvider per locale to force unmount on locale change, or provide an option to opt out of reapplying state from hidden trees.
  • Document incompatibility with cacheComponents/Activity for now.

Minimal reproduction (shape)

• Next.js 16 app with cacheComponents: true
• app/[locale]/layout.tsx + app/[locale]/page.tsx
• Providers with next-themes ThemeProvider wrapping the app
• A simple language switcher using locale routing and a theme switcher calling setTheme('light' | 'dark')
• Sequence above reliably reproduces in dev

Version

0.4.6

What browsers are you seeing the problem on?

Firefox

[pauksztello]

I’m experiencing the exact same issue. Have you found any workarounds?

[mburumaxwell]

A number of components were having similar errors for me. The key guideline from Vercel is to add suspense and one easy way is loading.{ts,js,tsx,jsx} . I added this at the root of the app (app/loading.tsx or src/app/loading.tsx) and it solved all these issues for me. Since it is at the root, I have it returning null and gives me room to override wherever I want.
This is the workaround I have working on 2 projects.
Example: mburumaxwell/paklo#2359
Perhaps this is not an issue with next-themes

[amjadfqs]

Try this:

<NextThemesProvider
  key={locale}  // ← This is the fix
  attribute="class"
  defaultTheme="system"
  enableColorScheme
  enableSystem
  storageKey="test-theme"
>

[r34son]

vercel/next.js#86577

[icyJoseph]

I have, #377, which doesn't directly address this but fixes it by making the theme an external store, rather than React state. In other words, React subscribes to both a media object and a thin layer around localStorage, to read theme values. A single on ThemeProvider doesn't hold a stale theme value anymore.

The key rotation is a valid approach though, or try to hoist the ThemeProvider so that there's only one, that's also a good idea.

I think the root of the issue was the applyTheme useEffect, that on Activity reveal, would re-sync and apply the theme saved by the ThemeProvider.

As a follow up for #377 I have #378 with an example and e2e with Cache Components - https://github.com/pacocoursey/next-themes/actions/runs/22438204680/job/64973473171?pr=378