[Portal] Explore giving more control for layering

We currently apply the maximum z-index on portals and have had a few requests to allow more control here. This ticket is to explore ways of allowing that for a few reasons:

• People have requested it
• Can only override all portal instances via the data-radix-portal attribute atm
• Other Radix components provide an API to control things (consistency)
• The data-radix-portal attribute is an inconsistent escape hatch that we removed from other comps

An initial discussion on this topic provided a couple ideas:

• A layer/zIndex prop for portalled parts, e.g. <DialogContent layer={3}>
• ~A Portal provider part exposed per component that provides its props to the internal portal, e.g. <DialogPortal style={{ zIndex: 3 }}><DialogContent /></DialogPortal>. The provider suggestion is because we need control internally of how/where/when the portal is rendered.~
• Expose a Portal part for people to wrap when they want portals, e.g. Dialog.Portal. Examples.
• Use Slot internally on the Portal. This would reduce elements rendered as an additional win but it wouldn’t work with:
  • Popper based parts because popper wraps its own additional div for positioning
  • Parts that use https://github.com/theKashey/react-remove-scroll because portal needs to wrap the RemoveScroll part for it to work, and RemoveScroll isn’t slot-aware.
• Any more for any more?

[jjenzz]

We’ve published a release candidate for this in Dialog and AlertDialog to try. The API has breaking changes with this change so we would love feedback on the approach before we roll it out across our other components.

The new anatomy is as follows:

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content />
  </Dialog.Portal>
</Dialog.Root>

Note:

• The Dialog.Content can be rendered inside Dialog.Overlay if preferred for styling purposes.
• The Dialog.Portal doesn’t render a div anymore so z-index styles can be applied to Dialog.Overlay/Dialog.Content directly.
• The Dialog.Portal can portal into a custom container using the container prop:

   const [container, setContainer] = React.useState(null);
   
   return (
     <>
       <Dialog.Root>
         <Dialog.Trigger />
         <Dialog.Portal container={container}>
           <Dialog.Overlay />
           <Dialog.Content />
         </Dialog.Portal>
       </Dialog.Root>
       <div ref={setContainer} />
     </>
   );
  

[pdong]

Having more control here would be really helpful. My use-case is that I’m using react-toastify to show toasts; on mobile I’m using modals as full-page takeovers and sometimes want to show a toast over it. I can use Portal to put my toasts above everything but since they’re always max z-index as soon as the overlay and modal mount they’re always on top of the toasts. Having a little wiggle room here would be helpful.

I think exposing Portal in the Dialog primitive makes sense and will allow more control over how the Dialog renders. It’s definitely a little more overhead but not much more than having to compose all the other parts anyway and will give developers much more control over how things behave.