Skip to content

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

Open

Description

@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

Activity

  1. pauksztello commented on Dec 23, 2025

    @pauksztello

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

  2. mburumaxwell commented on Dec 31, 2025

    @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

  3. amjadfqs commented on Jan 15, 2026

    @amjadfqs

    Try this:

    <NextThemesProvider
      key={locale}  // ← This is the fix
      attribute="class"
      defaultTheme="system"
      enableColorScheme
      enableSystem
      storageKey="test-theme"
    >
    
  4. r34son commented on Feb 18, 2026

    @r34son
  5. icyJoseph commented on Feb 26, 2026

    @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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingtriage

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions