Clarify behavior of Portal when target changes dynamically

[chuvashevskii]

Mantine Portal dynamic target behavior

Issue description

When using @mantine/core Portal, the portal does not move its content to a new container if the target prop changes dynamically for the same instance.

Instead, Portal looks up the DOM node and updates its internal ref in an effect, but since this does not trigger a re-render, the portal continues rendering into the old container until the component is fully remounted (for example, by changing key).

Minimal reproduction

import * as React from 'react';
import { Portal } from '@mantine/core';

const OUTLET_NAME = 'outlet';

const A = () => <div><h3>A</h3><div id={OUTLET_NAME} /></div>;
const B = () => <div><h3>B</h3><div id={OUTLET_NAME} /></div>;
const C = () => <div><h3>C</h3><div id={OUTLET_NAME} /></div>;

const VIEW_MAP = { A, B, C };

export default function App() {
  const [view, setView] = React.useState<'A' | 'B' | 'C'>('A');
  const Component = VIEW_MAP[view];

  return (
    <div>
      <button onClick={() => setView('A')}>Show A</button>
      <button onClick={() => setView('B')}>Show B</button>
      <button onClick={() => setView('C')}>Show C</button>
      <Component />
      <Portal target={`#${OUTLET_NAME}`}>
        <span>view name: {view}</span>
      </Portal>
    </div>
  );
}

Steps to reproduce:

1. Render component A with <div id="outlet" /> and a <Portal target="#outlet" />.
2. Switch to component B or C (they also have <div id="outlet" />).
3. Portal content stays in the previous outlet instead of moving to the new one.

Live demo & source

• 🔗 CodeSandbox: Open sandbox
• 🔗 Repository: Open repository

Expected behavior

It would be useful if either:

1. Portal supported dynamically following the new target, or
2. Documentation explicitly stated that target is not reactive within the same instance and that a remount (e.g. with key) is required to move the portal.

Proposal

Add a note to the documentation explaining this behavior:

• target is stored in a ref and updated inside an effect.
• Changing target does not trigger a re-render.
• If you need to move the portal, you must remount the Portal (for example, by using key).

Workarounds

• Force remount with key={someId} when the outlet changes.
• Wrap Mantine Portal and trigger a state update on target change.
• Use a custom portal built on top of ReactDOM.createPortal that always renders into the current target.

[rtivital]

Thanks for reporting, I'll update the documentation to include the information about the target prop.

[chuvashevskii]

Thank you very much for the quick reply and for clarifying!

I just wanted to add a note: in my case, the outlet node where I want to mount the portal can appear dynamically (for example, when switching steps in a multi-step form). Because of that, I created a small wrapper with PortalProvider, PortalTarget, and PortalOutlet that keeps a registry of available outlets and allows the portal to attach when the node appears.

If you have a chance, could you please take a quick look at my solution and let me know if this approach makes sense, or if there is a better way to handle such a case with Mantine Portal?

• 🔗 Sandbox: https://codesandbox.io/p/devbox/naughty-satoshi-z6rw95?file=%2Fsrc%2FApp.tsx
• 🔗 Repository: https://github.com/chuvashevskii/mantine-portal-with-dynamic-outlet/tree/main

[rtivital]

Do you use the Portal component as is and want to modify it? Or you use it as part of another component, like Modal? In first case, you can use createPortal function on your side directly. In the second case, I'd use the key prop.

[chuvashevskii]

I’ve solved the issue in the step component that has a loading state by moving the portal slot outside of the loading condition.
This way, the outlet

is always present in the DOM and does not depend on the component’s loading state.

As a result, the Portal can consistently attach to this slot and display the current step indicator, while the main content of the step (loading spinner or loaded data) changes independently.

return (
  <div className={s.root}>
    <Container className={s.root__container} size="sm">
      {/* The outlet is always rendered, regardless of loading */}
      <div id={STEP_INDICATOR_SLOT_ID} className={s.root__indicator} />
      {content}
    </Container>
  </div>
);