Portais React - Renderize filhos em um nó DOM fora da hierarquia DOM do componente pai

Q: O que createPortal faz e por que é necessário?

createPortal(children, domNode) renderiza filhos React em um nó DOM fora da hierarquia DOM do pai. É necessário para escapar de contextos de empilhamento CSS (overflow: hidden, contêineres z-index) que cortariam overlays. Casos de uso comuns incluem modais, tooltips, dropdowns e notificações toast.

Q: Armadilha: Por que createPortal falha durante a renderização do lado do servidor?

document.body não existe durante o SSR. Correção: proteja a renderização do portal com uma verificação de montagem acionada por useEffect ou use "use client" no Next.js.

Q: Qual é o tipo de retorno de createPortal em TypeScript?

createPortal retorna ReactPortal, que é um ReactNode válido. O segundo argumento deve ser um Element ou DocumentFragment, não null. Proteja com uma verificação condicional ou de estado para evitar passar null.

Q: Como tipar o parâmetro domNode de createPortal em TypeScript?

O tipo do parâmetro é Element | DocumentFragment. Ao usar uma ref ou estado para manter o contêiner, tipá-lo como HTMLElement | null e renderizar condicionalmente. Exemplo: const [container, setContainer] = useState(null);

Receita

import { createPortal } from "react-dom";
 
function Modal({ isOpen, onClose, children }: {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  if (!isOpen) return null;
 
  return createPortal(
    <div className="fixed inset-0 z-50 flex items-center justify-center">
      <div className="fixed inset-0 bg-black/50" onClick={onClose} />
      <div className="relative bg-white rounded-lg p-6 max-w-md w-full">
        {children}
      </div>
    </div>,
    document.body
  );
}
 
// Uso
<Modal isOpen={showModal} onClose={() => setShowModal(false)}>
  <h2>Confirmar ação</h2>
  <p>Tem certeza?</p>
</Modal>

Quando usar isso: Quando um componente precisa ser renderizado visualmente fora da árvore DOM de seu pai (modais, dropdowns, tooltips, toasts), mas ainda assim participar da árvore de eventos e contexto do React.

Exemplo de Trabalho

import { createPortal } from "react-dom";
import { useState, useEffect, useRef, useCallback, type ReactNode } from "react";
 
// --- Modal acessível com armadilha de foco ---
 
function Modal({
  isOpen,
  onClose,
  title,
  children,
}: {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: ReactNode;
}) {
  const dialogRef = useRef<HTMLDivElement>(null);
  const previousFocusRef = useRef<HTMLElement | null>(null);
 
  // Prende o foco e lida com a tecla Escape
  useEffect(() => {
    if (!isOpen) return;
 
    previousFocusRef.current = document.activeElement as HTMLElement;
    dialogRef.current?.focus();
 
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === "Escape") {
        onClose();
        return;
      }
 
      if (e.key === "Tab" && dialogRef.current) {
        const focusable = dialogRef.current.querySelectorAll<HTMLElement>(
          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
        );
        const first = focusable[0];
        const last = focusable[focusable.length - 1];
 
        if (e.shiftKey && document.activeElement === first) {
          e.preventDefault();
          last?.focus();
        } else if (!e.shiftKey && document.activeElement === last) {
          e.preventDefault();
          first?.focus();
        }
      }
    };
 
    document.addEventListener("keydown", handleKeyDown);
    document.body.style.overflow = "hidden";
 
    return () => {
      document.removeEventListener("keydown", handleKeyDown);
      document.body.style.overflow = "";
      previousFocusRef.current?.focus();
    };
  }, [isOpen, onClose]);
 
  if (!isOpen) return null;
 
  return createPortal(
    <div className="fixed inset-0 z-50 flex items-center justify-center">
      {/* Plano de fundo */}
      <div
        className="fixed inset-0 bg-black/50 animate-fade-in"
        onClick={onClose}
        aria-hidden="true"
      />
      {/* Diálogo */}
      <div
        ref={dialogRef}
        role="dialog"
        aria-modal="true"
        aria-label={title}
        tabIndex={-1}
        className="relative bg-white rounded-xl shadow-2xl p-6 max-w-lg w-full mx-4 animate-scale-in"
      >
        <div className="flex justify-between items-center mb-4">
          <h2 className="text-xl font-semibold">{title}</h2>
          <button
            onClick={onClose}
            aria-label="Fechar diálogo"
            className="p-1 rounded hover:bg-gray-100"
          >
            X
          </button>
        </div>
        {children}
      </div>
    </div>,
    document.body
  );
}
 
// --- Tooltip usando portal ---
 
function Tooltip({
  children,
  content,
}: {
  children: ReactNode;
  content: string;
}) {
  const [visible, setVisible] = useState(false);
  const [coords, setCoords] = useState({ top: 0, left: 0 });
  const triggerRef = useRef<HTMLSpanElement>(null);
 
  const show = useCallback(() => {
    if (triggerRef.current) {
      const rect = triggerRef.current.getBoundingClientRect();
      setCoords({
        top: rect.top - 8 + window.scrollY,
        left: rect.left + rect.width / 2 + window.scrollX,
      });
    }
    setVisible(true);
  }, []);
 
  return (
    <>
      <span
        ref={triggerRef}
        onMouseEnter={show}
        onMouseLeave={() => setVisible(false)}
        onFocus={show}
        onBlur={() => setVisible(false)}
      >
        {children}
      </span>
      {visible &&
        createPortal(
          <div
            role="tooltip"
            className="absolute -translate-x-1/2 -translate-y-full px-2 py-1 bg-gray-900 text-white text-sm rounded pointer-events-none"
            style={{ top: coords.top, left: coords.left }}
          >
            {content}
          </div>,
          document.body
        )}
    </>
  );
}
 
// --- Uso ---
function SettingsPage() {
  const [showConfirm, setShowConfirm] = useState(false);
 
  return (
    <div className="p-8">
      <h1>Configurações</h1>
      <Tooltip content="Isso excluirá todos os seus dados">
        <button
          onClick={() => setShowConfirm(true)}
          className="text-red-600 underline"
        >
          Excluir Conta
        </button>
      </Tooltip>
 
      <Modal
        isOpen={showConfirm}
        onClose={() => setShowConfirm(false)}
        title="Excluir Conta"
      >
        <p className="mb-4">Esta ação não pode ser desfeita. Tem certeza?</p>
        <div className="flex gap-2 justify-end">
          <button onClick={() => setShowConfirm(false)} className="btn-secondary">
            Cancelar
          </button>
          <button className="btn-danger">Excluir</button>
        </div>
      </Modal>
    </div>
  );
}

O que isso demonstra:

Portal de modal com armadilha de foco, tratamento da tecla escape e bloqueio de scroll
Portal de tooltip posicionado em relação ao seu elemento de gatilho
Atributos ARIA para acessibilidade (role="dialog", aria-modal, aria-label)
Restauração do foco anterior ao fechar o modal

Mergulho Profundo

Como Funciona

createPortal(children, domNode) renderiza children em domNode em vez do nó DOM do pai.
Apesar da colocação no DOM, os portais permanecem parte da árvore React. Contexto, eventos e estado fluem como se o portal ainda fosse um filho de seu pai React.
O borbulhamento de eventos funciona através da árvore React, não da árvore DOM. Um clique dentro de um portal irá borbulhar para o pai React, não para o pai DOM.
Portais são comumente usados para escapar de contextos de empilhamento CSS (overflow: hidden, contêineres z-index) que cortariam overlays.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Propósito
`children`	`ReactNode`	Os elementos React a serem renderizados no portal
`domNode`	`Element` ou `DocumentFragment`	O nó DOM para renderizar
`key` (opcional)	`string`	Chave única para o portal
Valor de retorno	`ReactPortal`	Um elemento React especial representando o portal

Variações

Contêiner de portal dinâmico - crie e limpe um nó DOM dedicado:

function usePortalContainer(id: string) {
  const [container, setContainer] = useState<HTMLElement | null>(null);
 
  useEffect(() => {
    let element = document.getElementById(id);
    if (!element) {
      element = document.createElement("div");
      element.id = id;
      document.body.appendChild(element);
    }
    setContainer(element);
 
    return () => {
      if (element && element.childNodes.length === 0) {
        element.remove();
      }
    };
  }, [id]);
 
  return container;
}
 
function ToastContainer({ children }: { children: ReactNode }) {
  const container = usePortalContainer("toast-root");
  if (!container) return null;
  return createPortal(children, container);
}

Portal compatível com servidor - proteja contra document ausente:

function ClientPortal({ children }: { children: ReactNode }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
 
  if (!mounted) return null;
  return createPortal(children, document.body);
}

Notas TypeScript

createPortal retorna ReactPortal, que é um ReactNode válido.
O segundo argumento deve ser um Element ou DocumentFragment, não null. Proteja com uma verificação condicional ou de estado.
Ao usar portais no Next.js, sempre proteja com uma verificação de montagem do lado do cliente, pois document não está disponível durante o SSR.

Armadilhas

Herança CSS quebrada - Estilos herdados de elementos DOM pais (fonte, cor) não se aplicam ao conteúdo portado, pois ele reside em outro lugar no DOM. Correção: Certifique-se de que o conteúdo portado defina seus próprios estilos base ou use um wrapper de reset CSS.
Erros de SSR - document.body não existe durante a renderização do lado do servidor. Correção: Proteja a renderização do portal com uma verificação de montagem acionada por useEffect ou use "use client".
Múltiplos portais e guerras de z-index - Vários portais renderizando para document.body podem empilhar de forma imprevisível. Correção: Use uma raiz de portal dedicada com um contexto de empilhamento, ou gerencie o z-index através de um gerenciador de portais.
Confusão no borbulhamento de eventos - Eventos borbulham através da árvore React, não da árvore DOM. Um clique dentro de um portal modal borbulha para o pai React, o que pode acionar manipuladores não intencionais. Correção: Use e.stopPropagation() no conteúdo do portal se o pai tiver manipuladores de clique concorrentes.
Gerenciamento de foco - Abrir um portal sem mover o foco deixa os usuários de teclado presos. Correção: Mova o foco para dentro do portal ao abrir e restaure-o ao fechar, como mostrado no exemplo de trabalho.

Alternativas

Abordagem	Contrapartida
`createPortal`	Controle total; gerenciamento manual de foco e acessibilidade
Elemento HTML `<dialog>`	Modal nativo com armadilha de foco integrada; estilo limitado
Radix Dialog / Headless UI	Acessibilidade completa integrada; dependência extra
CSS `position: fixed` sem portal	Mais simples; quebra dentro de pais com `overflow: hidden` ou `transform`
API Popover (`atributo popover`)	API nativa do navegador; suporte limitado do navegador e integração React

FAQs

O que `createPortal` faz e por que é necessário?

createPortal(children, domNode) renderiza filhos React em um nó DOM fora da hierarquia DOM do pai.
É necessário para escapar de contextos de empilhamento CSS (overflow: hidden, contêineres z-index) que cortariam overlays.
Casos de uso comuns incluem modais, tooltips, dropdowns e notificações toast.

Portais permanecem parte da árvore de componentes React, mesmo que renderizem em outro lugar no DOM?

Sim. Apesar da colocação no DOM, os portais permanecem parte da árvore React.
Contexto, eventos e estado fluem como se o portal ainda fosse um filho de seu pai React.
Esta é uma diferença chave em relação à adição manual de elementos DOM.

Como funciona o borbulhamento de eventos com portais?

Eventos borbulham através da árvore React, não da árvore DOM.
Um clique dentro de um portal modal borbulha para o pai React, não para o pai DOM (document.body).
Isso pode acionar manipuladores não intencionais no pai React. Use e.stopPropagation() se necessário.

Como implementar a armadilha de foco em um portal modal?

const focusable = dialogRef.current.querySelectorAll<HTMLElement>(
  'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
const first = focusable[0];
const last = focusable[focusable.length - 1];
 
if (e.shiftKey && document.activeElement === first) {
  e.preventDefault();
  last?.focus();
} else if (!e.shiftKey && document.activeElement === last) {
  e.preventDefault();
  first?.focus();
}

Consulte todos os elementos focáveis dentro do diálogo.
No Tab, envolva o foco do último para o primeiro (e vice-versa com Shift+Tab).

Armadilha: Por que o conteúdo portado perde estilos herdados de CSS?

O conteúdo portado reside em um local DOM diferente (por exemplo, document.body), portanto, não herda estilos pais como fonte, cor ou altura da linha.
Correção: certifique-se de que o conteúdo portado defina seus próprios estilos base ou use um wrapper de reset CSS.

Armadilha: Por que `createPortal` falha durante a renderização do lado do servidor?

document.body não existe durante o SSR.
Correção: proteja a renderização do portal com uma verificação de montagem acionada por useEffect ou use "use client" no Next.js.

const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return null;
return createPortal(children, document.body);

Qual é o tipo de retorno de `createPortal` em TypeScript?

createPortal retorna ReactPortal, que é um ReactNode válido.
O segundo argumento deve ser um Element ou DocumentFragment, não null.
Proteja com uma verificação condicional ou de estado para evitar passar null.

Como tipar o parâmetro `domNode` de `createPortal` em TypeScript?

O tipo do parâmetro é Element | DocumentFragment.
Ao usar uma ref ou estado para manter o contêiner, tipá-lo como HTMLElement | null e renderizar condicionalmente.
Exemplo: const [container, setContainer] = useState<HTMLElement | null>(null);

Como criar um contêiner de portal dinâmico que se limpa?

function usePortalContainer(id: string) {
  const [container, setContainer] = useState<HTMLElement | null>(null);
  useEffect(() => {
    let el = document.getElementById(id);
    if (!el) {
      el = document.createElement("div");
      el.id = id;
      document.body.appendChild(el);
    }
    setContainer(el);
    return () => { if (el && el.childNodes.length === 0) el.remove(); };
  }, [id]);
  return container;
}

Crie o contêiner na montagem e remova-o na desmontagem se estiver vazio.
Isso evita o acúmulo de nós DOM obsoletos.

Por que restaurar o foco ao fechar um portal modal?

Sem a restauração do foco, os usuários de teclado perdem seu lugar na página após o fechamento do modal.
Salve o elemento previamente focado antes de abrir o modal e chame .focus() nele na função de limpeza.
Este é um requisito de acessibilidade para diálogos.

Como múltiplos portais interagem com o empilhamento z-index?

Vários portais renderizando para document.body podem empilhar de forma imprevisível porque compartilham o mesmo contexto de empilhamento.
Correção: use uma raiz de portal dedicada com um contexto de empilhamento gerenciado, ou atribua valores z-index através de um gerenciador de portais.
Alternativamente, renderize portais em ordem de prioridade para que portais posteriores empilhem naturalmente sobre os anteriores.

Relacionado

Composição - Portais usam composição de filhos para injeção de conteúdo
Error Boundaries - Envolva portais em limites de erro para segurança
Componentes Compostos - Diálogos modais frequentemente usam APIs de componentes compostos

Receita

import { createPortal } from "react-dom";
 
function Modal({ isOpen, onClose, children }: {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  if (!isOpen) return null;
 
  return createPortal(
    <div className="fixed inset-0 z-50 flex items-center justify-center">
      <div className="fixed inset-0 bg-black/50" onClick={onClose} />
      <div className="relative bg-white rounded-lg p-6 max-w-md w-full">
        {children}
      </div>
    </div>,
    document.body
  );
}
 
// Uso
<Modal isOpen={showModal} onClose={() => setShowModal(false)}>
  <h2>Confirmar ação</h2>
  <p>Tem certeza?</p>
</Modal>

Exemplo de Trabalho

import { createPortal } from "react-dom";
import { useState, useEffect, useRef, useCallback, type ReactNode } from "react";
 
// --- Modal acessível com armadilha de foco ---
 
function Modal({
  isOpen,
  onClose,
  title,
  children,
}: {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: ReactNode;
}) {
  const dialogRef = useRef<HTMLDivElement>(null);
  const previousFocusRef = useRef<HTMLElement | null>(null);
 
  // Prende o foco e lida com a tecla Escape
  useEffect(() => {
    if (!isOpen) return;
 
    previousFocusRef.current = document.activeElement as HTMLElement;
    dialogRef.current?.focus();
 
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === "Escape") {
        onClose();
        return;
      }
 
      if (e.key === "Tab" && dialogRef.current) {
        const focusable = dialogRef.current.querySelectorAll<HTMLElement>(
          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
        );
        const first = focusable[0];
        const last = focusable[focusable.length - 1];
 
        if (e.shiftKey && document.activeElement === first) {
          e.preventDefault();
          last?.focus();
        } else if (!e.shiftKey && document.activeElement === last) {
          e.preventDefault();
          first?.focus();
        }
      }
    };
 
    document.addEventListener("keydown", handleKeyDown);
    document.body.style.overflow = "hidden";
 
    return () => {
      document.removeEventListener("keydown", handleKeyDown);
      document.body.style.overflow = "";
      previousFocusRef.current?.focus();
    };
  }, [isOpen, onClose]);
 
  if (!isOpen) return null;
 
  return createPortal(
    <div className="fixed inset-0 z-50 flex items-center justify-center">
      {/* Plano de fundo */}
      <div
        className="fixed inset-0 bg-black/50 animate-fade-in"
        onClick={onClose}
        aria-hidden="true"
      />
      {/* Diálogo */}
      <div
        ref={dialogRef}
        role="dialog"
        aria-modal="true"
        aria-label={title}
        tabIndex={-1}
        className="relative bg-white rounded-xl shadow-2xl p-6 max-w-lg w-full mx-4 animate-scale-in"
      >
        <div className="flex justify-between items-center mb-4">
          <h2 className="text-xl font-semibold">{title}</h2>
          <button
            onClick={onClose}
            aria-label="Fechar diálogo"
            className="p-1 rounded hover:bg-gray-100"
          >
            X
          </button>
        </div>
        {children}
      </div>
    </div>,
    document.body
  );
}
 
// --- Tooltip usando portal ---
 
function Tooltip({
  children,
  content,
}: {
  children: ReactNode;
  content: string;
}) {
  const [visible, setVisible] = useState(false);
  const [coords, setCoords] = useState({ top: 0, left: 0 });
  const triggerRef = useRef<HTMLSpanElement>(null);
 
  const show = useCallback(() => {
    if (triggerRef.current) {
      const rect = triggerRef.current.getBoundingClientRect();
      setCoords({
        top: rect.top - 8 + window.scrollY,
        left: rect.left + rect.width / 2 + window.scrollX,
      });
    }
    setVisible(true);
  }, []);
 
  return (
    <>
      <span
        ref={triggerRef}
        onMouseEnter={show}
        onMouseLeave={() => setVisible(false)}
        onFocus={show}
        onBlur={() => setVisible(false)}
      >
        {children}
      </span>
      {visible &&
        createPortal(
          <div
            role="tooltip"
            className="absolute -translate-x-1/2 -translate-y-full px-2 py-1 bg-gray-900 text-white text-sm rounded pointer-events-none"
            style={{ top: coords.top, left: coords.left }}
          >
            {content}
          </div>,
          document.body
        )}
    </>
  );
}
 
// --- Uso ---
function SettingsPage() {
  const [showConfirm, setShowConfirm] = useState(false);
 
  return (
    <div className="p-8">
      <h1>Configurações</h1>
      <Tooltip content="Isso excluirá todos os seus dados">
        <button
          onClick={() => setShowConfirm(true)}
          className="text-red-600 underline"
        >
          Excluir Conta
        </button>
      </Tooltip>
 
      <Modal
        isOpen={showConfirm}
        onClose={() => setShowConfirm(false)}
        title="Excluir Conta"
      >
        <p className="mb-4">Esta ação não pode ser desfeita. Tem certeza?</p>
        <div className="flex gap-2 justify-end">
          <button onClick={() => setShowConfirm(false)} className="btn-secondary">
            Cancelar
          </button>
          <button className="btn-danger">Excluir</button>
        </div>
      </Modal>
    </div>
  );
}

O que isso demonstra:

Portal de modal com armadilha de foco, tratamento da tecla escape e bloqueio de scroll
Portal de tooltip posicionado em relação ao seu elemento de gatilho
Atributos ARIA para acessibilidade (role="dialog", aria-modal, aria-label)
Restauração do foco anterior ao fechar o modal

Mergulho Profundo

Como Funciona

createPortal(children, domNode) renderiza children em domNode em vez do nó DOM do pai.
Apesar da colocação no DOM, os portais permanecem parte da árvore React. Contexto, eventos e estado fluem como se o portal ainda fosse um filho de seu pai React.
O borbulhamento de eventos funciona através da árvore React, não da árvore DOM. Um clique dentro de um portal irá borbulhar para o pai React, não para o pai DOM.
Portais são comumente usados para escapar de contextos de empilhamento CSS (overflow: hidden, contêineres z-index) que cortariam overlays.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Propósito
`children`	`ReactNode`	Os elementos React a serem renderizados no portal
`domNode`	`Element` ou `DocumentFragment`	O nó DOM para renderizar
`key` (opcional)	`string`	Chave única para o portal
Valor de retorno	`ReactPortal`	Um elemento React especial representando o portal

Variações

Contêiner de portal dinâmico - crie e limpe um nó DOM dedicado:

function usePortalContainer(id: string) {
  const [container, setContainer] = useState<HTMLElement | null>(null);
 
  useEffect(() => {
    let element = document.getElementById(id);
    if (!element) {
      element = document.createElement("div");
      element.id = id;
      document.body.appendChild(element);
    }
    setContainer(element);
 
    return () => {
      if (element && element.childNodes.length === 0) {
        element.remove();
      }
    };
  }, [id]);
 
  return container;
}
 
function ToastContainer({ children }: { children: ReactNode }) {
  const container = usePortalContainer("toast-root");
  if (!container) return null;
  return createPortal(children, container);
}

Portal compatível com servidor - proteja contra document ausente:

function ClientPortal({ children }: { children: ReactNode }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
 
  if (!mounted) return null;
  return createPortal(children, document.body);
}

Notas TypeScript

createPortal retorna ReactPortal, que é um ReactNode válido.
O segundo argumento deve ser um Element ou DocumentFragment, não null. Proteja com uma verificação condicional ou de estado.
Ao usar portais no Next.js, sempre proteja com uma verificação de montagem do lado do cliente, pois document não está disponível durante o SSR.

Armadilhas

Herança CSS quebrada - Estilos herdados de elementos DOM pais (fonte, cor) não se aplicam ao conteúdo portado, pois ele reside em outro lugar no DOM. Correção: Certifique-se de que o conteúdo portado defina seus próprios estilos base ou use um wrapper de reset CSS.
Erros de SSR - document.body não existe durante a renderização do lado do servidor. Correção: Proteja a renderização do portal com uma verificação de montagem acionada por useEffect ou use "use client".
Múltiplos portais e guerras de z-index - Vários portais renderizando para document.body podem empilhar de forma imprevisível. Correção: Use uma raiz de portal dedicada com um contexto de empilhamento, ou gerencie o z-index através de um gerenciador de portais.
Confusão no borbulhamento de eventos - Eventos borbulham através da árvore React, não da árvore DOM. Um clique dentro de um portal modal borbulha para o pai React, o que pode acionar manipuladores não intencionais. Correção: Use e.stopPropagation() no conteúdo do portal se o pai tiver manipuladores de clique concorrentes.
Gerenciamento de foco - Abrir um portal sem mover o foco deixa os usuários de teclado presos. Correção: Mova o foco para dentro do portal ao abrir e restaure-o ao fechar, como mostrado no exemplo de trabalho.

Alternativas

Abordagem	Contrapartida
`createPortal`	Controle total; gerenciamento manual de foco e acessibilidade
Elemento HTML `<dialog>`	Modal nativo com armadilha de foco integrada; estilo limitado
Radix Dialog / Headless UI	Acessibilidade completa integrada; dependência extra
CSS `position: fixed` sem portal	Mais simples; quebra dentro de pais com `overflow: hidden` ou `transform`
API Popover (`atributo popover`)	API nativa do navegador; suporte limitado do navegador e integração React

FAQs

O que `createPortal` faz e por que é necessário?

createPortal(children, domNode) renderiza filhos React em um nó DOM fora da hierarquia DOM do pai.
É necessário para escapar de contextos de empilhamento CSS (overflow: hidden, contêineres z-index) que cortariam overlays.
Casos de uso comuns incluem modais, tooltips, dropdowns e notificações toast.

Portais permanecem parte da árvore de componentes React, mesmo que renderizem em outro lugar no DOM?

Sim. Apesar da colocação no DOM, os portais permanecem parte da árvore React.
Contexto, eventos e estado fluem como se o portal ainda fosse um filho de seu pai React.
Esta é uma diferença chave em relação à adição manual de elementos DOM.

Como funciona o borbulhamento de eventos com portais?

Eventos borbulham através da árvore React, não da árvore DOM.
Um clique dentro de um portal modal borbulha para o pai React, não para o pai DOM (document.body).
Isso pode acionar manipuladores não intencionais no pai React. Use e.stopPropagation() se necessário.

Como implementar a armadilha de foco em um portal modal?

const focusable = dialogRef.current.querySelectorAll<HTMLElement>(
  'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
const first = focusable[0];
const last = focusable[focusable.length - 1];
 
if (e.shiftKey && document.activeElement === first) {
  e.preventDefault();
  last?.focus();
} else if (!e.shiftKey && document.activeElement === last) {
  e.preventDefault();
  first?.focus();
}

Consulte todos os elementos focáveis dentro do diálogo.
No Tab, envolva o foco do último para o primeiro (e vice-versa com Shift+Tab).

Armadilha: Por que o conteúdo portado perde estilos herdados de CSS?

O conteúdo portado reside em um local DOM diferente (por exemplo, document.body), portanto, não herda estilos pais como fonte, cor ou altura da linha.
Correção: certifique-se de que o conteúdo portado defina seus próprios estilos base ou use um wrapper de reset CSS.

Armadilha: Por que `createPortal` falha durante a renderização do lado do servidor?

document.body não existe durante o SSR.
Correção: proteja a renderização do portal com uma verificação de montagem acionada por useEffect ou use "use client" no Next.js.

const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return null;
return createPortal(children, document.body);

Qual é o tipo de retorno de `createPortal` em TypeScript?

createPortal retorna ReactPortal, que é um ReactNode válido.
O segundo argumento deve ser um Element ou DocumentFragment, não null.
Proteja com uma verificação condicional ou de estado para evitar passar null.

Como tipar o parâmetro `domNode` de `createPortal` em TypeScript?

O tipo do parâmetro é Element | DocumentFragment.
Ao usar uma ref ou estado para manter o contêiner, tipá-lo como HTMLElement | null e renderizar condicionalmente.
Exemplo: const [container, setContainer] = useState<HTMLElement | null>(null);

Como criar um contêiner de portal dinâmico que se limpa?

function usePortalContainer(id: string) {
  const [container, setContainer] = useState<HTMLElement | null>(null);
  useEffect(() => {
    let el = document.getElementById(id);
    if (!el) {
      el = document.createElement("div");
      el.id = id;
      document.body.appendChild(el);
    }
    setContainer(el);
    return () => { if (el && el.childNodes.length === 0) el.remove(); };
  }, [id]);
  return container;
}

Crie o contêiner na montagem e remova-o na desmontagem se estiver vazio.
Isso evita o acúmulo de nós DOM obsoletos.

Por que restaurar o foco ao fechar um portal modal?

Sem a restauração do foco, os usuários de teclado perdem seu lugar na página após o fechamento do modal.
Salve o elemento previamente focado antes de abrir o modal e chame .focus() nele na função de limpeza.
Este é um requisito de acessibilidade para diálogos.

Como múltiplos portais interagem com o empilhamento z-index?

Vários portais renderizando para document.body podem empilhar de forma imprevisível porque compartilham o mesmo contexto de empilhamento.
Correção: use uma raiz de portal dedicada com um contexto de empilhamento gerenciado, ou atribua valores z-index através de um gerenciador de portais.
Alternativamente, renderize portais em ordem de prioridade para que portais posteriores empilhem naturalmente sobre os anteriores.

Relacionado

Composição - Portais usam composição de filhos para injeção de conteúdo
Error Boundaries - Envolva portais em limites de erro para segurança
Componentes Compostos - Diálogos modais frequentemente usam APIs de componentes compostos

Portais React - Renderize filhos em um nó DOM fora da hierarquia DOM do componente pai

Buscar na documentação

Portais React - Renderize filhos em um nó DOM fora da hierarquia DOM do componente pai