Portales en React: createPortal para modales y tooltips

Un portal renderiza parte de un componente en otro lugar del DOM, normalmente document.body, mientras sigue en el mismo lugar del árbol de React. Lo creas con createPortal(children, domNode) de react-dom. Los portales son la forma en que los modales, tooltips y menús desplegables escapan de un padre que tiene overflow: hidden o su propio contexto de apilamiento.

La caja de abajo recorta todo lo que sobresale. Abre ambos tips.

import { useState } from 'react';
import { createPortal } from 'react-dom';

const tipStyle = { position: 'absolute', width: 150, padding: 8, background: '#222', color: '#fff', borderRadius: 6, fontSize: 13 };

export default function App() {
    const [inlineOpen, setInlineOpen] = useState(false);
    const [portalPos, setPortalPos] = useState(null);

    function togglePortal(e) {
        if (portalPos) return setPortalPos(null);
        const r = e.currentTarget.getBoundingClientRect();
        setPortalPos({ top: r.bottom + window.scrollY + 6, left: r.left + window.scrollX });
    }

    return (
        <div>
            <div style={{ position: 'relative', overflow: 'hidden', height: 60, maxWidth: 340, padding: 8, border: '2px dashed #999', display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start' }}>
                <button onClick={() => setInlineOpen(!inlineOpen)}>Normal tip</button>
                <button onClick={togglePortal}>Portal tip</button>
                {inlineOpen && (
                    <div style={{ ...tipStyle, top: 44, left: 8 }}>
                        I render inside the box, so its overflow: hidden cuts me off.
                    </div>
                )}
            </div>
            {portalPos &&
                createPortal(
                    <div style={{ ...tipStyle, ...portalPos }}>
                        I render into document.body, so nothing clips me.
                    </div>,
                    document.body,
                )}
            <div style={{ height: 90 }} />
        </div>
    );
}

El tip normal queda cortado en el borde punteado. El tip del portal aparece completo, porque su nodo DOM es hijo de <body>, no de la caja. Borra overflow: 'hidden' de la caja y el tip normal deja de recortarse.

La sintaxis

import { createPortal } from 'react-dom';

createPortal(children, domNode, key?)

• children es cualquier JSX: un elemento, un fragmento, un componente.
• domNode es un elemento del DOM existente, como document.body o document.getElementById('modal-root'). Debe existir cuando el portal se renderiza.
• key es opcional, para cuando renderizas una lista de portales.

createPortal devuelve algo que pones en tu JSX como cualquier elemento. No renderiza nada en la posición del DOM propia del padre.

Un modal en document.body

Un modal es el caso clásico. Dentro de una tarjeta con un transform, un overlay con position: fixed se posiciona respecto a esa tarjeta en lugar de la ventana, y el overflow: hidden de la tarjeta lo recorta. Renderizado en document.body, cubre toda la ventana.

import { useEffect, useRef, useState } from 'react';
import { createPortal } from 'react-dom';

function Modal({ title, onClose, children }) {
    const closeRef = useRef(null);

    useEffect(() => {
        closeRef.current.focus();
        function onKey(e) {
            if (e.key === 'Escape') onClose();
        }
        document.addEventListener('keydown', onKey);
        return () => document.removeEventListener('keydown', onKey);
    }, [onClose]);

    return createPortal(
        <div onClick={onClose} style={{ position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.4)', display: 'grid', placeItems: 'center' }}>
            <div role="dialog" aria-modal="true" aria-labelledby="modal-title" onClick={(e) => e.stopPropagation()} style={{ background: '#fff', padding: 16, borderRadius: 8, width: 240 }}>
                <h3 id="modal-title" style={{ marginTop: 0 }}>{title}</h3>
                {children}
                <button ref={closeRef} onClick={onClose}>Close</button>
            </div>
        </div>,
        document.body,
    );
}

export default function App() {
    const [open, setOpen] = useState(false);

    return (
        <div style={{ transform: 'scale(1)', overflow: 'hidden', border: '1px solid #ccc', padding: 12 }}>
            <p>A card with transform and overflow: hidden.</p>
            <button onClick={() => setOpen(true)}>Open modal</button>
            {open && (
                <Modal title="Delete draft?" onClose={() => setOpen(false)}>
                    <p>The overlay covers the whole frame, not just the card.</p>
                </Modal>
            )}
        </div>
    );
}

Abre el modal y luego pulsa Escape o haz clic en el overlay oscuro para cerrarlo. Al abrirse, el foco pasa al botón Close. Ahora devuelve el overlay sin createPortal (quita la llamada y su argumento document.body): el overlay se reduce al tamaño de la tarjeta, porque transform convierte la tarjeta en el bloque contenedor de los elementos fijos.

Los eventos se propagan por el árbol de React

Un portal cambia dónde vive el nodo del DOM, no dónde vive el componente. Los eventos de React se propagan hacia arriba por el árbol de React, así que un clic dentro de un portal llega al onClick del componente que lo renderizó, aunque en el DOM el botón sea hijo de <body>.

Los listeners nativos son distintos. Un listener agregado con addEventListener sigue el árbol del DOM y nunca ve el clic.

import { useEffect, useRef } from 'react';
import { createPortal } from 'react-dom';

export default function App() {
    const wrapperRef = useRef(null);

    useEffect(() => {
        const node = wrapperRef.current;
        const onNativeClick = () => console.log('native listener on the wrapper div');
        node.addEventListener('click', onNativeClick);
        return () => node.removeEventListener('click', onNativeClick);
    }, []);

    return (
        <div
            ref={wrapperRef}
            onClick={(e) => console.log('React onClick on the wrapper, target:', e.target.textContent)}
            style={{ padding: 12, border: '2px dashed #999' }}
        >
            <button>Inside the wrapper</button>
            {createPortal(<button style={{ margin: 16 }}>In a portal</button>, document.body)}
        </div>
    );
}

Haz clic en "Inside the wrapper": registran tanto el manejador de React como el listener nativo. Haz clic en "In a portal": solo registra el manejador de React. El botón del portal está fuera del envoltorio punteado en pantalla, y aun así React lo sigue tratando como hijo.

Normalmente esto es lo que quieres: un onClick en el padre de un menú ve los clics en los elementos de su portal, y los proveedores de contexto que están por encima del componente también se aplican dentro del portal. Puede sorprenderte con la lógica de "clic fuera para cerrar". Un onClick en un envoltorio que cierra un menú también se dispara con los clics dentro del portal del menú, así que detén la propagación dentro del menú (e.stopPropagation(), explicado en la página de eventos), o usa un listener nativo en document y comprueba si el target está dentro del nodo DOM del portal.

Portales en tu propio contenedor

document.body es el destino más simple. Algunas apps agregan un contenedor dedicado a index.html para que todos los overlays compartan un lugar y un orden de apilamiento:

<body>
    <div id="root"></div>
    <div id="modal-root"></div>
</body>

createPortal(<Modal />, document.getElementById('modal-root'));

Con renderizado en el servidor (Next.js y otros frameworks), document no existe en el servidor. Renderiza el portal solo después de que el componente se haya montado, por ejemplo detrás de un estado mounted que un efecto pone en true.

Cuando el portal tiene que posicionarse junto a su disparador, mide primero el disparador. El primer ejemplo lo mide en el manejador de clic; para un tooltip que no debe parpadear, mide en useLayoutEffect, que se ejecuta antes de que el navegador pinte.

Modales accesibles

Mover el marcado a document.body no hace nada por sí solo para los usuarios de teclado y de lectores de pantalla. Un modal también necesita:

• role="dialog" y aria-modal="true", con aria-labelledby apuntando a su título.
• Mover el foco dentro del diálogo al abrirlo (el ejemplo da foco a Close), y devolverlo al botón que lo abrió al cerrarlo.
• Escape para cerrar.
• Mantener el foco dentro mientras está abierto, para que Tab no recorra la página de detrás. Poner el atributo inert en la raíz de la app mientras el modal está abierto bloquea ahí el foco y los clics.

El elemento nativo <dialog> maneja casi todo esto por ti. Abierto con dialogRef.current.showModal(), se dibuja en la capa superior del navegador por encima de cualquier z-index, deja inerte el resto de la página y se cierra con Escape. No necesita un portal, así que es una buena opción por defecto para diálogos de confirmación simples; los portales siguen siendo la herramienta para tooltips, menús y overlays personalizados.

Por qué z-index no basta

Los desarrolladores suelen recurrir a un portal cuando un z-index grande no consigue poner un menú por encima del resto de la página. La razón son los contextos de apilamiento. Un elemento con position y un z-index, un opacity menor que 1, un transform, un filter o isolation: isolate inicia un nuevo contexto de apilamiento, y los valores de z-index de sus hijos solo compiten entre sí dentro de él. Un hijo con z-index: 9999 dentro de una tarjeta con z-index: 1 sigue quedando debajo de una tarjeta hermana con z-index: 2.

Un portal saca el elemento de todos esos ancestros. Como hijo de <body>, su z-index se compara con los elementos de nivel superior de la página, así que un valor modesto como 1000 basta para los overlays.

Errores comunes

Hacer un portal hacia un nodo que todavía no existe. document.getElementById('modal-root') devuelve null si falta el elemento, y createPortal lanza "Target container is not a DOM element". Revisa el HTML, o haz el portal hacia document.body.

Crear el nodo de destino durante el renderizado. Escribir document.createElement('div') en el cuerpo del componente crea un nodo nuevo en cada renderizado. Créalo una vez en un efecto, o usa un contenedor fijo.

Popups que no siguen a su disparador. Un tooltip posicionado con getBoundingClientRect() no sigue a su disparador cuando la página se desplaza o cambia de tamaño. Vuelve a calcular en scroll y resize (y quita esos listeners en la limpieza del efecto), o cierra el tooltip cuando la página se desplace.