[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?