<Dialog /> / <Portal /> custom root element

[michael-land]

What package within Headless UI are you using?

@headlessui/react

What version of that package are you using?

1.0.0

What browser are you using?

chrome

Reproduction repository

I'm rendering my react app under shadow root and all my css are scoped inside the shadow root.

I want the <Dialog /> or the <Portal /> insert inside the shadow root instead of the document.body. It would be nice we can pass custom root element for <Dialog /> / <Portal />.

[SigurdMW]

Any update on this? This is a feature we would like as well 😄

[zawilliams]

Running into this same issue. Custom root element would be great.

[rikkipitt]

Same here. I think I'm running into a similar thing...

[MarcelMalik]

Same issue here. Workaround: must use a custom modal implementation :/

[xylophonehero]

Would be great to have this feature. My custom Modal implementation isn't as good as this one 😢. Using styled components and my CSS is scoped to the top of my shadow too. A custom element for where the portal should be rendered would be a great implementation!

[dcastil]

I also have the use case where I don't want to use a portal because the dialog needs to be positioned based on the element close to which the React component is rendered. The dialog takes in most of the screen space, the background gets blurred while the dialog is open and I want to trap the focus in the dialog, so using a Popover wouldn't be the right choice here.

I need to use a different library for this although the functionality is basically the same as the Headless UI dialog.

Would be awesome if Headless UI could support not using a portal at all! ❤️

[yaakov123]

I have an unbelievably hacky solution, but it works (sort of).

Paste the following code as early as possible (index.ts or something)

const elementById = Document.prototype.getElementById;
Document.prototype.getElementById = function (elementId: string) {
  if (elementId === "headlessui-portal-root") {
    return root.element; // This is the root element which exists inside the Shadow DOM
  }
  return elementById.call(this, elementId);
};

The issue now is that clicking anywhere closes the Modal

[yaakov123]

This issue can be solved by removing the @close listener from the Dialog component and manually placing it on the overlay

[yaakov123]

I've written a more complete solution here - #874 (comment)

[jtomaszewski]

Dialog should allow for customizing what's/where's the portal root node.

This will solve problems like:

• this one
• Can't style Dialog when prefixing tailwind classes with a selector #998

Until then, devs have to choose a different Dialog implementation, or go around with hacks (like replacing the Document.prototype.getElementById or creating <div id="headlessui-portal-root" /> by themselves and making sure it's recreated between dialog mounts/dismounts).

@RobinMalfait tell me that you'd be open to this, and I can raise a PR.

[yassilah]

thanks a lot, works for me too 🙂

[okpedro]

P.S. For now, as a simplier workaround, you can just do

<React.Fragment>
  <YourAppThatUsesDialogs ... />
  
  {/* Workaround for https://github.com/tailwindlabs/headlessui/discussions/666 */}
  <div id="headlessui-portal-root">
    {/* It needs at least one child, so that HeadlessUI doesn't remove this portal root workaround
        ( https://github.com/tailwindlabs/headlessui/blob/main/packages/@headlessui-react/src/components/portal/portal.tsx#L84 ) */}
    <div />
  </div>
</React.Fragment>

I found that if I set it to <div/> or an empty <div></div>, it doesn't work. Even if I put whitespace in there or fill it with content and hide it, it won't work. But if I put a single visible character, like <div>i</div>, it works. Otherwise, the modal opens and closes in a flash. I'm scratching my head trying to figure out why that matters.

EDIT: Figured out <div/> only doesn't work if the <Dialog> component is set to fixed instead of relative, in which case the <div> needs some visible content.

[steph-crown]

When I did this, clicking on the dialog itself closes the dialog. @jtomaszewski please, do you have any fix for that.

[paweltatarczuk]

@steph-crown I encountered a similar issue and had to use a different workaround in my case. The dialog was not interactive because of an inert tag that was added to an ancestor of the <div id="headlessui-portal-root">. Since I was using this workaround only for scoped styles, I decided to solve it with the postcss-prefix-selector plugin instead.

[sturmenta]

@steph-crown my fix was (suggested by @thevisioner here)

remove the inert tag from the root component that I was using:

import { useEffect } from "react";

export const useRemoveInert = ({ isModalOpen }: { isModalOpen: boolean }) => {
  useEffect(() => {
    if (isModalOpen) {
      // timeout needed to make sure inert is removed after dialog is opened
      setTimeout(() => {
        // disable inert to make dialog interactive -> https://github.com/tailwindlabs/headlessui/discussions/666#discussioncomment-6183443
        const rootNode = document.getElementById("your-root-id");
        if (rootNode) rootNode.inert = false;
      }, 100);
    }
  }, [isModalOpen]);
};

[sbarbat]

For some reason non of the solutions here helped me, so listening to changes in the DOM and then moving the portal root to wherever I wanted worked for me:

// Just create the container and shadow root
let container = document.getElementById('some-container');
if (!container) {
  container = document.createElement('div');
  container.id = 'some-container';
  document.body.appendChild(container);
}
const shadow = container.shadowRoot ?? container.attachShadow({ mode: 'open' });

/**
 * Every time a new element `headlessui-portal-root` is added to the DOM,
 * it will place it into the shadow body inside `some-container`
 */
new MutationObserver((records: MutationRecord[]) => {
  const record: MutationRecord | undefined = records
    .filter((record) => (record.target as HTMLElement).id === 'headlessui-portal-root')
    .pop();

  if (!record) return;
  shadow.append(record.target);
}).observe(document, { childList: true, subtree: true });

[sbarbat]

Yes, that something I'm facing, do you know why this might be happening?

[yaakov123]

You can take a look at my solution here for a working fix: #874 (comment)

[animber0]

@yaakov123 This one works for me, but can you help me understand how to convert this solution to yours, or what the fundamental differences are?

[RomainMazB]

Because the inert attribute is added to the HTML element hosting the Vue app (probably #app)
A simpler solution is to move the div#headlessui-portal-root outside of your Vue app.

As mentioned in the vue doc it won't affect the Portal behavior:

Sometimes a part of a component's template belongs to it logically, but from a visual standpoint, it should be displayed somewhere else in the DOM, perhaps even outside of the Vue application.

<body>
    <div id="app"></div> <!-- Will receive the inert attribute -->

    <div id="headlessui-portal-root">
        <div></div>
    </div>
</body>

[leizzo]

@yaakov123 if the dialogue is set to open by default, your solution does not work correctly. but as for my problem, if the opened dialogue is closed and you want to open it again, it does not work. I could not solution for this :/

[pfcodes]

Forcing a single portal that is unmodifiable is a pretty big architectural flaw imo. We should be able to use our own like Radix UI does https://www.radix-ui.com/docs/primitives/components/dialog#custom-portal-container

[curtgrimes]

I really need this for my use case.

[loicmagne]

🙏

[alifatic]

i still got this issue in "@headlessui/react": "^1.6.6", please any fix, other solution does not fix this

[lukeclifton]

I have the same issue here. As a work around i am doing the following:

<div id="headlessui-portal-root" class="tailwind-important-class-or-id">
    <div id="react-app-root-id"></div>
</div>

[web-programmer-here]

any updates on this?

[ScripterSugar]

Why is this issue not fixed after 3 years of initial raise? any particular reason?

This flaw significantly affects the main concept of headless UI - fully customizable, the modal component is completely useless for my usecase because of this ;*(

[axe312ger]

Have to agree :(

Edit:

Well, there is id="headlessui-portal-root" which tells headless ui where to put the portal. Works fine for me! :)

[Welfordian]

Was there any solution found for this problem? :-(

[TrustyTechSG]

I facing the Dialog display issue when rendering Dialog in iframe (using react-frame-component), the Dialog will always attach to the outer window instead of the iframe window.

[heronoa]

The way I solve it was to set a Modal on the my template root (the first element that will render and use context to open and close it. TL;DR I think I create my own modal but still use Transitions from headlessUI to animate it

[wade-wojcak-vib]

Wanted to chime in with my use case where I stumbled on this issue:

I am using Storybook + React and was testing out a Dialog. I have a wrapper around my Stories at the preview level which applies my custom font. This works fine for the baseline rendering of a Story, but when a Dialog Portal is created it is created outside of that wrapper and thus does not retain the font.

I can fix this for an initial Dialog opening by defining a div with id = 'headlessui-portal-root' within my Stories rendering function, but this gets wiped out after you close and reopen the Dialog a second time. Given this issue is just in a testing environment I will probably just overlook it for now, but it would be nice to have a way to define a permanent portal root if necessary.

[SampsonCrowley]

this makes it impossible to have more than one root (i.e. separate apps on the same page)

It also makes it soe that you can't guarantee certain dialogs are at a higher stacking context than others

[ChaseIngebritson]

Chiming in with another workaround for usage in Storybook using the removeInert hook from @sturmenta and the storybook tips from @wade-wojcak-vib:

export const Default: Story = {
  args: {
    open: false
  },
  render: function Render(args) {
    const [open, setOpen] = useState(args.open)

    // This can be extracted into a hook, but for the sake of example it's not
    useEffect(() => {
      if (open) {
        setTimeout(() => {
          const rootNode = document.getElementById('storybook-root')
          if (rootNode) rootNode.inert = false
        }, 100)
      }
    }, [open])

    return (
      <>
        <div id="headlessui-portal-root" />
        <MeshProviderMock mocks={globalQueryMocks}>
          <SaturateCacheMock>
            <ButtonPrimary label="Toggle" onClick={() => setOpen(!open)} />
            {/* This EditorDialog component is a thin wrapper for the headlessui dialog component and is not rendered until the button is clicked */}
            {open && <EditorDialog open={open} />}
          </SaturateCacheMock>
        </MeshProviderMock>
      </>
    )
  }
}

Note that the headlessui portal root component needs to exist in the dom before the headlessui dialog component has been rendered, otherwise it won't detect that a root already exists in the ownerDocument

[johnnyshankman]

-1 this only works for me on the first opening. if i close the dialog, it removes my predefined headless portal root from the dom and then proceeds to do default behavior upon opening the dialog a second time.

[AshleySchaeffer]

Not ideal, but in React I was trying to have notifications appear over all other elements. This issue caused me problems. I just did this:

https://react.dev/reference/react-dom/createPortal#rendering-a-modal-dialog-with-a-portal

It creates another portal which renders as expected.

[KrishEnacton]

Can you provide me a full example of it?

[AshleySchaeffer]

https://codesandbox.io/p/sandbox/6c6clm

If you click the button in the top right of the code snippets on the docs, you'll see a full example hosted on codesandbox.

I don't fully understand it, but it looks like portals dynamically create elements at the document root. I just defined a portal in the component and it worked fine, even rendering after a modal component rendered within another portal.

As the notification component renders after the modal, it's portal element renders above the modal.

[johnnyshankman]

This is so silly that we can't predefine where the portal goes to using a prop.

<div id="headlessui-portal-root" />

You can try putting this in your DOM but it will only hook into it one time. Once you close the Dialog, it will remove this element and then reinject it in the default spot. So silly.

Took me twenty minutes reading through this to find my solve:

  {/* It needs at least one child, so that HeadlessUI doesn't remove this portal root workaround
        ( https://github.com/tailwindlabs/headlessui/blob/main/packages/@headlessui-react/src/components/portal/portal.tsx#L84 ) */}

[johnnyshankman]

Oh great but now the z-indexing is completely screwed so I cannot click on anything inside my dialogs. I give up what an awful library. Seems like an obvious thing you'd want to control. I don't just want portals opening up at the root of the document.

[AshleySchaeffer]

Oh great but now the z-indexing is completely screwed so I cannot click on anything inside my dialogs. I give up what an awful library. Seems like an obvious thing you'd want to control. I don't just want portals opening up at the root of the document.

See my solution. It worked for me. Might work for you.

[GianlucaGuarini]

I have just figured out that with <div id="headlessui-poral-root"> workaround the dialog is broken. The inert attribute is not properly rendered through the DOM hierarchy (see also #3632).

Please make sure to upvote this discussion in order to let the maintainers accept PRs to fix this annoying issue #3563

[edda]

I have the same problem that I need my portal root to be rendered inside the shadow root. Not being able to set a custom portal root element is causing me so much extra work because I now have to manually take care of positioning everywhere, it's very frustrating!

Alternatively I would also take not having the headlessui portal forced on me if using anchor positioning. If I could use anchor and set portal={false} at the same time and then create my own portal around the component that would also work for me.

[ercgrat]

I also need to be able to customize the portal root. I am using components from several libraries that render dialog-type things, and I shuttle them all into a custom <div id="modal-root"> that appears as the sibling element after my main app content. I need dialogs to be inserted into the modal root in the order that they were opened so that everything stacks in the right order (e.g. nested modals/drawers, popovers on top of modals). I've worked around this by portaling the headless-ui modal content, but then I need to do extra work to remove inert where it's inappropriately injected. Super frustrating.

[Crocsx]

Came here to post this one to. While there are 99% of case where you want portal on body, there are some cases, specifically due to design compromise, where it is necessary to display a drawer for exemple into a container and this is almost impossible or highly inconvenient to do in css.

Having the ability to define a container for the portal in those rare case would be a big win.

Would be nice to have some maintainer opinion cause it's been 3 years of discussion and this feature is clearly a popular one

[mikeskydev]

I would also love a solution, my use case is a WebXR App that uses the DOM Overlay module, which renders using top-layer (explainer). This means that all Dialogs appear underneath the rest of my XR UI...

[boris-etingof-flarehr]

Here's the approach that works for me. I render a Headless UI Dialog inside a web component, but when it's teleported outside, the component's shadow-DOM styles no longer apply. To fix this, I observe mutations on document.body. As soon as a headlessui-portal-root element is added, I move it back into the component's shadow root, when it's removed, I clean up the shadow root.

I'm on "@headlessui/react": "1.7.16"

The code lives in the top-level App.tsx, outside the component function.

const headlessuiPortalRootId = 'headlessui-portal-root';
const webComponentTagName = 'my-web-component';

const findHeadlessPortalRootNodes = (nodes: NodeList) => {
  return Array.from(nodes).some(
    (n): n is HTMLElement =>
      n instanceof HTMLElement && n.id === headlessuiPortalRootId,
  );
};

(() => {
  const move = (mutations: MutationRecord[]) => {
    const {added, removed} = mutations.reduce<{
      added?: boolean;
      removed?: boolean;
    }>(
      (memo, {addedNodes, removedNodes}) => ({
        added: findHeadlessPortalRootNodes(addedNodes) || memo.added,
        removed: findHeadlessPortalRootNodes(removedNodes) || memo.removed,
      }),
      {},
    );

    const root = document.getElementById(headlessuiPortalRootId);
    const target = document.querySelector(webComponentTagName)?.shadowRoot;

    if (added && root?.firstChild) {
      target?.appendChild(root.firstChild);
    }

    if (removed) {
      const portals = target?.querySelectorAll('[data-headlessui-portal]');
      portals?.forEach(el => el.remove());
    }
  };

  const docObs = new MutationObserver(move);
  docObs.observe(document.body, {childList: true});

  return () => {
    docObs.disconnect();
  };
})();

const App: FC = () => {
   ...
}

export default App;