[cache components]: Client component's state during route navigation

[MiniCodeCamper]

In Next.js 16, when cacheComponents is enabled, the client component's state is preserved during route navigation. However, when cacheComponents is disabled, the state is lost. What causes this behavior?

[icyJoseph]

When Cache Components is enabled, we also wrap Activity components around routes. I just merged the docs update w/ this behavior. Be aware that there's a known issue with Portals. Tracked upstream here: facebook/react#35000

[MiniCodeCamper]

Oh, amazing! Thank you.

[icyJoseph]

https://nextjs.org/docs/app/getting-started/cache-components#navigation-with-cache-components for completeness sake

[bolechen]

We're experiencing this Portal issue with shadcn/ui Sidebar (which uses Radix Dialog) in a route group layout scenario:

Scenario:

• ReadSidebar component lives in (read) route group layout
• Mobile only: Sidebar renders as a Sheet (Radix Dialog Portal)
• When navigating from /r/[pageId] → /all (cross-layout navigation)
• The (read) layout unmounts, but Portal DOM remains in document.body

Main UI Bug:
When the mobile Sidebar is open during cross-layout navigation:

• ❌ The Sidebar stays visible on the new page (/all)
• ❌ Portal DOM elements are not cleaned up
• ❌ Background overlay remains visible
• ❌ Users see leftover UI from the previous route

This happens because:

1. Next.js 16 Cache Components wraps routes with Activity components
2. The layout unmounts during cross-layout navigation
3. Radix Dialog's closing animation (~300ms) is async
4. Portal cleanup fails due to the React 19 issue mentioned in #35000

Current Workaround:

useEffect(() => {
  return () => {
    // Wait 500ms for React's async cleanup attempt
    setTimeout(() => {
      // Manually remove leftover Portal DOM
      const sidebarElements = document.querySelectorAll('[data-slot="sidebar"]');
      sidebarElements.forEach(element => {
        const portalContainer = findPortalContainer(element);
        if (portalContainer?.parentNode && document.body.contains(portalContainer)) {
          portalContainer.parentNode.removeChild(portalContainer);
        }
      });
    }, 500);
  };
}, []);

Questions:

1. Is manual DOM cleanup the recommended approach for Portals in route group layouts that get unmounted?
2. Should we handle this differently to avoid the 500ms delay?
3. Would love to hear if there's a cleaner pattern we're missing!

@icyJoseph Thanks for the clarification on Cache Components behavior! 🙏

[bolechen]

Update: Found an Elegant Solution Using Custom Portal Container

@bolechen We encountered the same issue with shadcn/ui Sidebar and found a much better solution than manual DOM cleanup!

The Root Cause

When Activity sets the route to "hidden", it applies display: none to the layout wrapper. However, Portals mounted to document.body are NOT affected by this, causing them to remain visible.

// Test result: Portal not managed by Activity
{
  "sidebar-wrapper": {
    "display": "none !important"  // ✅ Layout elements correctly hidden
  },
  "sidebar-portal": {
    "display": "flex",             // ❌ Portal still visible!
    "isVisible": true
  }
}

Our Solution: Custom Portal Container

Instead of manual DOM cleanup, we move the Portal into the layout so Activity can manage it automatically.

Step 1: Make Sidebar accept a custom Portal container (minimal changes to shadcn/ui components)

// src/components/ui/sidebar.tsx
import * as SheetPrimitive from "@radix-ui/react-dialog"
import { Sheet, SheetPortal, SheetOverlay } from "@/components/ui/sheet"

function Sidebar({ 
  portalContainer,  // ✅ New optional prop
  ...props 
}: React.ComponentProps<"div"> & {
  portalContainer?: HTMLElement | null
}) {
  if (isMobile) {
    return (
      <Sheet open={openMobile} onOpenChange={setOpenMobile}>
        {/* 🎯 Use Radix UI's native container prop */}
        <SheetPortal container={portalContainer}>
          <SheetOverlay />
          <SheetPrimitive.Content {...contentProps}>
            {children}
          </SheetPrimitive.Content>
        </SheetPortal>
      </Sheet>
    )
  }
}

Step 2: Create a container ref in the route group layout

// src/app/(read)/_components/layout/read-sidebar.tsx
export const ReadSidebar = ({ ... }) => {
  const portalContainerRef = useRef<HTMLDivElement>(null);

  return (
    <div ref={portalContainerRef}>  {/* Portal mount point */}
      <Sidebar portalContainer={portalContainerRef.current} {...props}>
        {/* Sidebar content */}
      </Sidebar>
    </div>
  );
};

Why This Works

Before:

<body>
  <div id="__next">
    <div style="display: none !important">  <!-- Activity hidden -->
      <div ref={containerRef}></div>
    </div>
  </div>
  <div data-radix-portal>  <!-- ❌ Still visible! -->
    <dialog>Sidebar content</dialog>
  </div>
</body>

After:

<body>
  <div id="__next">
    <div style="display: none !important">  <!-- Activity hidden -->
      <div ref={containerRef}>
        <div data-radix-portal>  <!-- ✅ Hidden with container! -->
          <dialog>Sidebar content</dialog>
        </div>
      </div>
    </div>
  </div>
</body>

Benefits

✅ No manual DOM manipulation - relies entirely on React and Next.js built-in mechanisms
✅ Respects React architecture - Portal still managed by React component tree
✅ Automatic cleanup - Activity hidden mechanism sets display: none automatically
✅ No race conditions - no need to handle React cleanup timing issues
✅ No delays - works immediately, no 500ms timeout needed
✅ Minimal changes - only adds an optional prop, fully backward compatible

Testing

• ✅ Open mobile Sidebar in /r/[pageId]
• ✅ Navigate to /all (cross-layout)
• ✅ Dialog elements completely cleaned up
• ✅ Visual check: page is clean, no leftover UI

This approach leverages Radix UI's native container prop (officially supported) and Next.js 16's Activity component working together as designed.

Hope this helps! 🎉

[mm-xitms]

Is there currently no way to opt out of this? Are there plans to add the option to opt out?

[icyJoseph]

Could you share how is this affecting you? if at all? or is just wanting to opt-out?

[mm-xitms]

Our codebase currently has a very large number of pages which have forms in them. These forms have to be empty when navigated to, and <Activity> breaks this - the previous form state is shown when the user navigates to a form after previously having submitted it.

In order to enable cache components, we would have to go through each of these forms and manually reset the state on onmount. It would be much easier for us the be able to opt out of this behavior.

If this seems like an non-general issue that is very specific to our codebase, then we completely understand if it’s not something worth addressing at the framework level. We just wanted to share our use case in case others might run into similar issues.

[icyJoseph]

Hi

I think you can do this right?

import { Activity, useReducer } from "react";

export default function App() {
  const [state, toggle] = useReducer((x) => !x, false);
  return (
    <>
      <button onClick={toggle}>Toggle</button>
      <br />

      <Activity mode={state ? "hidden" : "visible"}>
        <div>
          <form
            ref={(node) => {
              return () => {
                node?.reset(); // --> comment out and the form won't reset
              };
            }}
          >
            <input type="text" defaultValue="fooo" />
          </form>
        </div>
      </Activity>
    </>
  );
}

https://codesandbox.io/p/devbox/react-portal-activity-forked-whqj9g

[mm-xitms]

Thanks for the reply.

After playing with this for the last couple of days, our wish for the ability to opt out has only increased.
While this change may be useful in some cases, it goes against the expectations and habits of both developers and users: most of us expect the state to refresh on navigation. It just introduces a ton of unexpected footguns.

In our opinion, the preservation of state on navigation should be looked at as a feature onto itself and is quite easy to implement if the need for it arises - this should not be a default without an opt-out.

[ziyak97]

Just saw this been struggling with custom solutions for awhile and could not figure out why my unmounting was not working. This breaks so much existing code it definitely should not be the default.

[icyJoseph]

That's why it was introduced as part of a major release, within an opt-in flag.

We are monitoring and collecting feedback though. One thing to consider is that eventually, as per current Activity implementation, both library code and user land code need to start handling these cases, or provide control flags to let the developer decide, because a given tree might be rendered within an Activity.

The original PR talks about allowing to control the number of routes that are kept (caps at 3 at the moment), but we'll see, no promises just yet.

[ziyak97]

Thank you. I think it should be strongly considered though, because this will break some core shadcn components like drawers (and from the looks of it sheets and dialogs as well). On mobile it is common to have drawers for quick actions that navigate you to different pages.

For people who are not aware that this is due to cacheComponents (like me), will be puzzled and assume something is wrong with their own code.

In my case I really struggled (spent an entire day trying to figure this out) and now have a custom complicated solution to handle this.

I would never have thought that this is a cacheComponents issue until i happened to find this.

@shadcn maybe if possible there can be an update to components to fix this issue?

[JesperCph]

It’s been a major pain for us as well, and we eventually had to completely opt out of cacheComponents.

Our applications have hundreds of dedicated form routes, and once they’re implicitly wrapped in and no longer unmount on navigation, everything breaks from a UX and logic standpoint. It’s not just form state that gets preserved, all useState values are kept alive, even in places where unmounting has always been the natural reset mechanism.

A concrete example:
We have parallel routes that render a containing a form. The dialog relies on a useEffect that listens to the form action’s success state. On first submission, it shows a success toast and calls router.back().

With cacheComponents enabled, after that first submit, every future navigation to that same parallel route reuses the stale component state. So instead of opening the dialog again, it instantly triggers the success toast and router.back(), making the dialog impossible to access. The component effectively becomes “stuck” in its previous state forever.

Issues like this quickly compound across a large codebase. Retrofitting manual reset logic for hundreds of forms, dialogs, drawers, and components that naturally expect to unmount is simply not realistic.

State preservation on navigation can absolutely be useful, but not as an implicit global behavior that requires every component to suddenly become “Activity-aware”. Right now it feels forced on us in a way that breaks long-established patterns, very similar to the aggressive caching in Next 13.

I really think this needs to be opt-in, or at least offer a clear and granular opt-out at the route/layout level. These features are powerful, but without an escape hatch they can be extremely disruptive to existing, fully correct application logic.

[NathanAlkurdi]

Want to anecdotally contribute that persisting state between navigation can undesirably leak user data. I've encountered instances wherein a user on the same tab signs in, performs behaviors that are stateful, logs out, and another user logins during that same local session, leads to the recent user being able to see the previous user's existing state.

With the mechanisms of react activity when cacheComponents are enabled, developers will need to make significant refactors (in breadth) to ensure sensitive state at the very least is reinitialized appropriately under those circumstances.

[icyJoseph]

This was a good example. Thanks for that we've been able to repro it.

[NathanAlkurdi]

Appreciate the confirmation! To illustrate this more for others as well, the biggest surprise for me in this case when I was working through the next.js 15 to 16 upgrade, was when I observed stateful persistence around my login/sign-up forms. In the scenario I described in my initial post, it was possible for the existing user's login / password to still be persisted across sessions on the same tab, when users hit the login page route 😬

[NathanAlkurdi]

The surface area of this problem is certainly isolated to a subset of users, most likely to friends and family using the same device, however it is still unacceptable behavior, hence I would recommend folks urgently confirm forms are being reinitialized properly if you are on Next.js 16 and using cache components. Do not upgrade and jump to the new caching mechanisms in the current state of the beta without this due diligence.

This was probably inferable, but I would like to explicitly call out that I am in the camp of having a first-party solution around this, whether it be granular options to prevent Activity wrapping a page route when cache components on or other more generalized / abstracted levers.

[ziyak97]

Tbh i don’t understand how this continuing to be the default behaviour is even an option. It basically makes cacheComponents unusable on most projects.

@icyJoseph

[JesperCph]

I agree this is a major limitation. For our use case it effectively blocks adoption of cacheComponents.

We do want to use "use cache" and see a lot of potential in it, but the current default behavior of wrapping all routes in <Activity> makes it impossible to enable cacheComponents in our applications.

[icyJoseph]

Right now I can only ask to keep on adding feedback, but mostly use cases, for example #85502 (comment) was a really good one.

[vladishel]

This change is highly frustrating. I do not understand the rationale behind altering React’s default behavior to preserve client state across navigations.
With every release, changes are introduced and marketed as improvements or steps toward greater consistency. At the same time, however, fundamental React concepts are repeatedly abandoned. We saw this previously with fetch, and now again with client-side state handling.
In my specific case, I can no longer use cached components because this behavior breaks the unmount logic of a client-side React Three Fiber component. As a result, previously valid and predictable patterns are no longer reliable.
It is unclear why client components cannot remain fully dynamic, while caching is handled explicitly and exclusively on the server side—exactly as many developers initially expected. This would preserve established client-side behavior while still enabling powerful server-side optimizations.
At the very least, there should be a clear opt-out mechanism for such behavior changes. I strongly encourage considering backward compatibility and real-world client-side use cases more carefully in future design decisions.

[jonasg339]

I don't understand how this can be considered as default behaviour without an option to opt-out. Wrapping routes inside Activity to preserve state should be TOTALLY opt-int.
Consider this example:
A data-heavy application where you create/update data objects via forms - a very typical use case actually.
Just as an example, the created data objects are displayed in a table and clickable - when you click one you visit a route where the form for editing this data object appears pre-filled with the current values of that object.
Typical for such a situation where those forms can get really complex is to rely on client state libraries like react-hook-form for example -> therefore the form values are tied to the client state, so far so good.

In the old model without Activity wrapped routes (cacheComponents disabled), the data for this route gets loaded inside a Suspense, then propagated to the client side form. This lead to fresh data when you click a data object in the table - because data got dynamically loaded inside an RSC every time, and client state got re-created on a new route visit.

In the new model WITH Activity wrapped routes, everything about this behaviour is broken. You essentially cannot use client side libraries for form state management anymore. More detailed: If i click on a data object the first time, the route is visited and the form is prefilled correctly with fresh data. If i now go back and someone else/or something server side leads to a data change in that object and then i revisit that route i still see my old data due to client state preserving. Even though the new changed data is correctly fetched inside the RSC, its not getting applied correctly since the client state is not re-initialized with the new data, therefore i see my old out-of-date client state. And there is actually no way to change this behaviour at the moment without working around this with some sketchy manual client state clearing.

I don't think this is what you wanted to achieve with cacheComponents in the first place - you wanted to deliver more control and flexibility about what is getting cached and what not, and then force us to cache ALL client state? This isn't flexible at all and basically makes cacheComponents unusable outside of the lab.

Please make this Activity client state thing opt-in on a route level and then write a BIG section about it in the docs for cacheComponents.