tutoriales.com

React Portals: Renderizando Componentes Fuera del Árbol DOM Jerárquico ✨

Este tutorial explora React Portals, una característica poderosa que permite renderizar componentes hijos en un nodo DOM que existe fuera de la jerarquía DOM del componente padre. Descubrirás cómo usar Portals para resolver problemas comunes con el posicionamiento CSS, los eventos y la accesibilidad en modales, tooltips y otros componentes superpuestos.

Intermedio10 min de lectura10 views
Reportar error

Introducción a React Portals ✨

En el desarrollo de aplicaciones React, a menudo nos encontramos con la necesidad de renderizar un componente en una ubicación del DOM que no es su posición natural dentro del árbol jerárquico de componentes. Esto es particularmente cierto para elementos como modales, tooltips, menús desplegables y notificaciones, que necesitan "flotar" por encima del resto del contenido, sin ser afectados por los estilos overflow: hidden o z-index de sus padres. Aquí es donde React Portals entran en juego, ofreciendo una solución elegante y poderosa.

React Portals proporcionan una forma de renderizar hijos en un nodo DOM que existe fuera de la jerarquía DOM del componente padre. Aunque el componente hijo se renderiza físicamente en otro lugar del DOM, lógicamente permanece como un hijo del componente React que lo renderizó. Esto significa que mantiene el mismo contexto y comportamiento de eventos que si estuviera en su ubicación natural, lo que simplifica enormemente la gestión del estado y la lógica.

Este tutorial te guiará a través de los fundamentos de React Portals, te mostrará cómo implementarlos y te dará ejemplos prácticos de sus casos de uso más comunes.

¿Qué Problemas Resuelven los Portals? 🤔

Antes de sumergirnos en el cómo, entendamos el porqué. Sin Portals, manejar ciertos tipos de UI puede ser complicado:

  1. Problemas de Posicionamiento y z-index: Los componentes como los modales o tooltips necesitan superponerse a todo lo demás. Si un componente modal es hijo de un elemento con overflow: hidden o tiene un z-index bajo en su jerarquía, puede que no se muestre correctamente o quede truncado. Moverlo físicamente al final del <body> es una práctica común para evitar esto, pero dificulta la gestión del estado y eventos.

  2. Eventos Burbujeantes: Aunque los Portals renderizan en un nodo DOM diferente, los eventos burbujean a través de la jerarquía de componentes de React como si el componente hijo estuviera en su lugar original. Esto significa que un onClick en un modal dentro de un Portal seguirá siendo capturado por un padre de React que escucha ese evento.

  3. Accesibilidad: Para elementos como modales, es crucial controlar el foco del teclado y otras consideraciones de accesibilidad. Los Portals facilitan la creación de componentes de accesibilidad complejos al desacoplar su ubicación física de su ubicación lógica en el árbol de React.

💡 Consejo: Piensa en Portals como una teletransportación. Tu componente se crea en un lugar, pero mágicamente aparece en otro, manteniendo todas sus conexiones lógicas.

Diagrama Comparativo: Sin Portals vs. Con Portals

ESCENARIO 1: Sin Portals ESCENARIO 2: Con Portals document.body App Div (overflow: hidden) Modal Cortado Problemas Visuales document.body div#root App Component div#modal-root Modal (Portal) Jerarquía Lógica Portals desacoplan el renderizado físico de la lógica de React
```

Aquí, <div id="modal-root"></div> será el objetivo de nuestros portales. Puedes tener múltiples contenedores si necesitas diferentes tipos de portales (por ejemplo, uno para modales y otro para tooltips).

Paso 2: Crear el Componente Portal en React

Ahora, crearemos un componente React que envolverá a nuestro contenido y lo renderizará en el nodo modal-root.

// components/ModalPortal.jsx
import { useEffect, useRef } from 'react';
import { createPortal } from 'react-dom';

function ModalPortal({ children }) {
  const elRef = useRef(null);
  if (!elRef.current) {
    elRef.current = document.createElement('div');
  }

  useEffect(() => {
    const modalRoot = document.getElementById('modal-root');
    if (!modalRoot) {
      console.error('El elemento #modal-root no fue encontrado en el DOM.');
      return;
    }
    modalRoot.appendChild(elRef.current);

    return () => {
      modalRoot.removeChild(elRef.current);
    };
  }, []);

  return createPortal(children, elRef.current);
}

export default ModalPortal;

Analicemos este código:

  • elRef = useRef(null);: Creamos una referencia persistente para un div que será el punto de montaje intermedio para createPortal. Aunque el createPortal se conecta directamente al modal-root, a menudo es útil tener un div intermedio para controlar su ciclo de vida y poder añadirle estilos específicos si es necesario. En este caso, lo usamos para asegurar que createPortal siempre recibe el mismo elemento DOM para montar el children.
  • useEffect(() => { ... });: Este useEffect se encarga de montar y desmontar nuestro div auxiliar (elRef.current) al modal-root del DOM.
    • Cuando el componente ModalPortal se monta, añade elRef.current como hijo de modal-root.
    • Cuando el componente ModalPortal se desmonta, limpia el elRef.current del modal-root.
  • return createPortal(children, elRef.current);: Aquí está la magia. createPortal toma children (lo que le pasemos a ModalPortal) y lo renderiza dentro de elRef.current. Aunque elRef.current es a su vez hijo de modal-root, esto asegura que los hijos lógicos del Portal se rendericen en el lugar correcto del DOM.
📌 Nota: En este ejemplo, el `elRef.current` es el *contenedor físico* de los hijos del portal. El `modal-root` es el *contenedor maestro* donde se adjuntan estos contenedores intermedios. Podríamos pasar directamente `modalRoot` a `createPortal`, pero el enfoque con un `elRef.current` individual por portal es útil para gestionar múltiples modales o para aplicar estilos específicos a cada instancia de portal sin afectar a otros.

Paso 3: Usar el Componente Portal

Ahora podemos usar ModalPortal como cualquier otro componente en React.

// App.jsx
import React, { useState } from 'react';
import ModalPortal from './components/ModalPortal';
import './App.css'; // Para algunos estilos básicos

function App() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div className="App">
      <h1>Ejemplo de React Portals</h1>
      <div className="content-wrapper">
        <p>Este es el contenido principal de la aplicación.</p>
        <button onClick={() => setShowModal(true)}>Abrir Modal</button>

        {showModal && (
          <ModalPortal>
            <div className="modal-overlay" onClick={() => setShowModal(false)}>
              <div className="modal-content" onClick={e => e.stopPropagation()}> {/* Evita cerrar el modal al hacer clic dentro */}
                <h2>¡Mi Modal con Portal!</h2>
                <p>Este contenido se renderiza en el 'modal-root' del DOM.</p>
                <button onClick={() => setShowModal(false)}>Cerrar Modal</button>
              </div>
            </div>
          </ModalPortal>
        )}
      </div>
    </div>
  );
}

export default App;

/* App.css */
.App {
  text-align: center;
  padding: 20px;
}

.content-wrapper {
  border: 2px dashed #ccc;
  padding: 50px;
  margin: 50px auto;
  max-width: 600px;
  height: 300px;
  overflow: auto; /* Esto podría causar problemas sin portals */
  position: relative;
}

/* Estilos para el modal */
.modal-overlay {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: rgba(0, 0, 0, 0.7);
  display: flex;
  justify-content: center;
  align-items: center;
  z-index: 1000; /* Aseguramos que esté encima de todo */
}

.modal-content {
  background: white;
  padding: 30px;
  border-radius: 8px;
  box-shadow: 0 5px 15px rgba(0, 0, 0, 0.3);
  max-width: 500px;
  z-index: 1001;
}

.modal-content h2 {
  margin-top: 0;
  color: #333;
}

.modal-content button {
  margin-top: 20px;
  padding: 10px 20px;
  border: none;
  background-color: #007bff;
  color: white;
  border-radius: 5px;
  cursor: pointer;
  font-size: 16px;
}

.modal-content button:hover {
  background-color: #0056b3;
}

Observa que, a pesar de que el ModalPortal se usa dentro del <div className="content-wrapper"> (que tiene overflow: auto), el modal se renderiza a pantalla completa porque está físicamente fuera de esa jerarquía, directamente bajo modal-root en el <body>. Sin embargo, showModal y setShowModal aún controlan su visibilidad desde el componente App, demostrando que la lógica del estado permanece en el árbol de componentes React.

Casos de Uso Comunes para React Portals 🎯

Los Portals son increíblemente útiles en varios escenarios:

1. Modales y Diálogos ✅

Este es el caso de uso más frecuente. Los modales necesitan superponerse al resto de la aplicación y a menudo requieren un fondo opaco que cubra toda la ventana gráfica. Usar un Portal asegura que el modal no sea afectado por los estilos CSS de overflow o z-index de sus elementos padres en el árbol de React.

Ejemplo de estructura de un Modal completo 
// components/Modal.jsx
import React, { useEffect, useRef } from 'react';
import { createPortal } from 'react-dom';

const Modal = ({ children, isOpen, onClose }) => {
  const modalRoot = document.getElementById('modal-root');
  const elRef = useRef(null);
  if (!elRef.current) {
    elRef.current = document.createElement('div');
  }

  useEffect(() => {
    if (isOpen) {
      modalRoot.appendChild(elRef.current);
      // Opcional: enfocar el modal o un elemento dentro para accesibilidad
      // elRef.current.focus(); 
    }

    return () => {
      if (isOpen && modalRoot.contains(elRef.current)) {
        modalRoot.removeChild(elRef.current);
      }
    };
  }, [isOpen, modalRoot]);

  if (!isOpen) return null;

  return createPortal(
    <div className="modal-overlay" onClick={onClose}>
      <div className="modal-content" onClick={(e) => e.stopPropagation()}>
        {children}
      </div>
    </div>,
    elRef.current
  );
};

export default Modal;

Uso en un componente padre:

// components/MyComponent.jsx
import React, { useState } from 'react';
import Modal from './Modal';

function MyComponent() {
  const [showLoginModal, setShowLoginModal] = useState(false);

  return (
    <div>
      <button onClick={() => setShowLoginModal(true)}>Abrir Login</button>
      <Modal isOpen={showLoginModal} onClose={() => setShowLoginModal(false)}>
        <h3>Iniciar Sesión</h3>
        <p>Formulario de inicio de sesión aquí...</p>
        <button onClick={() => setShowLoginModal(false)}>Cerrar</button>
      </Modal>
    </div>
  );
}

export default MyComponent;

2. Tooltips y Popovers Contextuales 💬

Los tooltips a menudo necesitan aparecer justo al lado de un elemento, pero pueden tener problemas si el elemento padre tiene un overflow: hidden o si están cerca del borde de la pantalla. Usar un Portal les permite romper esas restricciones visuales mientras aún reciben datos y eventos de su componente padre lógico.

🔥 Importante: Para tooltips, aunque el Portal maneja la renderización fuera del árbol, la posición precisa (absoluta o fija) del tooltip dentro de la pantalla aún debe calcularse y aplicarse con CSS o JavaScript. Librerías como Popper.js o Floating UI son excelentes para esto y pueden integrarse fácilmente con Portals.

3. Notificaciones y Mensajes Toast 🔔

Las notificaciones suelen aparecer en una esquina de la pantalla, independientemente de dónde se active el evento que las dispara. Un Portal es perfecto para esto, ya que las notificaciones pueden vivir en su propia sección del DOM, lejos del flujo normal de la aplicación, pero aún gestionadas por el estado de React.

4. Menús Desplegables y Selectores Personalizados 🔽

Similar a los tooltips, los menús desplegables a veces necesitan "escapar" de los límites de un contenedor padre con estilos restrictivos. Un Portal puede asegurar que el menú completo sea visible, sin importar la configuración de su padre.

Accesibilidad con React Portals ♿

La accesibilidad es un aspecto crítico, especialmente para componentes que se superponen a la interfaz de usuario. Al usar Portals para modales y diálogos, es fundamental implementar las prácticas de accesibilidad correctas:

  • Gestión del Foco: Cuando un modal se abre, el foco debe moverse al modal (típicamente al primer elemento enfocable dentro de él). Cuando el modal se cierra, el foco debe regresar al elemento que lo activó. Esto se puede lograr con useRef y useEffect.
  • Trampa de Foco (Focus Trap): El foco debe permanecer dentro del modal mientras esté abierto. Los usuarios no deberían poder tabular fuera del modal. Esto se implementa monitoreando los eventos de teclado (Tab, Shift + Tab) y redirigiendo el foco si intenta escapar.
  • Roles y Atributos ARIA: Utiliza los roles ARIA apropiados, como role="dialog" o role="alertdialog", junto con atributos como aria-modal="true" y aria-labelledby para describir el contenido del modal a los lectores de pantalla.
  • Cierre con Escape: Permite que el modal se cierre al presionar la tecla Escape. Puedes añadir un useEffect en tu componente Modal para escuchar este evento.
Accesibilidad: 90% cubierta con Portals + buenas prácticas

Consideraciones y Mejores Prácticas 💡

Al trabajar con React Portals, ten en cuenta las siguientes consideraciones:

  • Rendimiento: Los Portals no afectan negativamente el rendimiento de forma inherente. El proceso de renderizado de React sigue siendo eficiente, incluso si el nodo DOM final está en otro lugar.
  • Gestión del Ciclo de Vida: El componente que renderiza el Portal sigue siendo el padre lógico. Esto significa que los contextos (Context API), los eventos de React (onClick, etc.) y el ciclo de vida fluyen como si no hubiera un Portal. Esto es una gran ventaja.
  • Limpieza: Asegúrate de que el elemento DOM que usas como contenedor para el Portal se limpie cuando el componente que lo gestiona se desmonte. Nuestro ejemplo ModalPortal ya lo hace con el useEffect.
  • Estilos: Los estilos CSS aplicados al contenido dentro del Portal deben considerarse cuidadosamente. Generalmente, es mejor usar estilos globales o scoped que no dependan demasiado de la cascada de estilos del padre lógico, ya que el padre físico es diferente.
  • Múltiples Portals: Puedes tener múltiples Portals activos al mismo tiempo, cada uno apuntando a un nodo DOM diferente o al mismo nodo si tu lógica lo requiere. Para modales, es común que solo uno esté activo a la vez.

Patrón de uso de Portals para componentes reutilizables

Un patrón común es crear un hook usePortal o un componente PortalProvider para gestionar el nodo raíz del portal y simplificar su uso en toda la aplicación.

Ejemplo de Custom Hook `usePortal` 
// hooks/usePortal.js
import { useRef, useEffect, useState } from 'react';
import { createPortal } from 'react-dom';

function createPortalRoot() {
  const portalRoot = document.getElementById('portal-root');
  if (portalRoot) return portalRoot;

  const newPortalRoot = document.createElement('div');
  newPortalRoot.setAttribute('id', 'portal-root');
  document.body.appendChild(newPortalRoot);
  return newPortalRoot;
}

function usePortal(id = 'portal-root') {
  const elRef = useRef(null);
  const [portalRoot, setPortalRoot] = useState(null);

  useEffect(() => {
    // Aseguramos que el elRef.current exista para createPortal
    if (!elRef.current) {
      elRef.current = document.createElement('div');
    }

    const target = document.getElementById(id) || createPortalRoot();
    setPortalRoot(target);

    target.appendChild(elRef.current);

    return () => {
      if (target.contains(elRef.current)) {
        target.removeChild(elRef.current);
      }
      // Opcional: Si el portalRoot fue creado dinámicamente, considerarlo remover si está vacío.
      // if (target.id === 'portal-root' && target.children.length === 0) {
      //   document.body.removeChild(target);
      // }
    };
  }, [id]);

  // Devuelve la función para renderizar el contenido dentro del portal
  const Portal = ({ children }) => {
    if (!portalRoot || !elRef.current) return null;
    return createPortal(children, elRef.current);
  };

  return Portal;
}

export default usePortal;

Cómo usarlo:

// App.jsx (o cualquier componente)
import React, { useState } from 'react';
import usePortal from './hooks/usePortal';

function App() {
  const [showNotification, setShowNotification] = useState(false);
  const NotificationPortal = usePortal('notification-root'); // Podemos especificar un ID diferente

  return (
    <div>
      <button onClick={() => setShowNotification(true)}>Mostrar Notificación</button>
      {showNotification && (
        <NotificationPortal>
          <div style={{ position: 'fixed', top: '20px', right: '20px', background: 'lightgreen', padding: '15px', borderRadius: '5px', zIndex: 9999 }}>
            ¡Notificación recibida!
            <button onClick={() => setShowNotification(false)}>X</button>
          </div>
        </NotificationPortal>
      )}
    </div>
  );
}

Resumen y Conclusión ✅

React Portals son una herramienta invaluable en tu arsenal de desarrollo React. Te permiten superar las limitaciones del DOM y el CSS cuando necesitas que los componentes se rendericen en ubicaciones específicas de la interfaz de usuario (como modales, tooltips o notificaciones) sin romper el flujo de datos y eventos de React. Al desacoplar la ubicación física de un componente de su ubicación lógica, Portals simplifican la creación de experiencias de usuario complejas y accesibles.

Recuerda siempre:

  • Estructura del DOM: Asegúrate de tener un nodo DOM objetivo en tu index.html (o créalo dinámicamente).
  • ReactDOM.createPortal(): Es la función clave para la magia.
  • Ciclo de Vida: Gestiona la adición y eliminación de tu nodo intermedio del DOM con useEffect.
  • Accesibilidad: Es crucial prestar atención a la gestión del foco y los atributos ARIA al usar Portals para modales y diálogos.

Con un buen entendimiento de React Portals, estarás bien equipado para construir interfaces de usuario más robustas, flexibles y con un mejor rendimiento.

Recursos Adicionales 📖

Tutoriales relacionados

Comentarios (0)

Aún no hay comentarios. ¡Sé el primero!