re:re:actable
Урок 104 минуты чтения

Порталы: createPortal для модалок, тултипов и тостов

На этой странице
Кратко

Портал (createPortal(children, domNode)) рендерит часть React-дерева в другой DOM-узел — обычно в document.body или специальный контейнер. Компонент остаётся частью React-дерева родителя: получает его контекст, состояние и props, а события из портала всплывают по дереву React (до React-родителя), а не по DOM. Зачем: вырваться из overflow: hidden, z-index-контекста и transform родителя — типичная проблема модальных окон, выпадающих меню, тултипов, тостов. Сегодня часть задач решают нативные <dialog> и Popover API (top layer без портала), а порталы остаются для своих оверлеев и встраивания React в чужой DOM.

Вопрос

Что такое порталы в React, когда они нужны и как ведут себя события и контекст внутри портала?

Проблема

<div className="card" style={{ overflow: 'hidden', transform: 'translateZ(0)' }}>
  <button onClick={() => setOpen(true)}>Подробнее</button>
  {open && <Modal />} {/* модалка обрежется рамками карточки и окажется под шапкой */}
</div>

overflow: hidden обрезает потомков, transform и z-index создают новый контекст наложения — position: fixed внутри перестаёт быть «фиксированным относительно окна».

Решение через портал

import { useEffect, useRef } from 'react';
import { createPortal } from 'react-dom';
 
export function Modal({ title, onClose, children }) {
  const closeRef = useRef(null);
 
  useEffect(() => {
    closeRef.current?.focus();
    const onKey = (e) => e.key === 'Escape' && onClose();
    document.addEventListener('keydown', onKey);
    return () => document.removeEventListener('keydown', onKey);
  }, [onClose]);
 
  return createPortal(
    <div className="backdrop" onClick={onClose}>
      <div
        role="dialog"
        aria-modal="true"
        aria-labelledby="modal-title"
        className="modal"
        onClick={(e) => e.stopPropagation()} // клик внутри окна не закрывает его
      >
        <h2 id="modal-title">{title}</h2>
        {children}
        <button ref={closeRef} onClick={onClose}>Закрыть</button>
      </div>
    </div>,
    document.body,
  );
}
function BookCard({ book }) {
  const [open, setOpen] = useState(false);
  return (
    <div className="card">
      <button onClick={() => setOpen(true)}>Подробнее</button>
      {open && (
        <Modal title={book.title} onClose={() => setOpen(false)}>
          <p>{book.description}</p>
        </Modal>
      )}
    </div>
  );
}

В DOM модалка — последний ребёнок <body>. В React она — ребёнок BookCard: видит его контексты (тема, i18n, роутер), а setOpen работает как обычно.

События всплывают по дереву React

<div onClick={() => console.log('клик дошёл до карточки')}>
  {createPortal(<button>Внутри портала</button>, document.body)}
</div>

Клик по кнопке выведет сообщение, хотя в DOM кнопка не внутри div. Это удобно (обработчики родителя работают), но может удивить: например, «клик вне меню» через onClick на родителе сработает и для кликов внутри портала. Поэтому внутри модалок часто ставят stopPropagation.

Контейнер и SSR

function Portal({ children }) {
  const [container, setContainer] = useState(null);
  useEffect(() => setContainer(document.getElementById('portal-root')), []);
  return container ? createPortal(children, container) : null; // на сервере document нет
}

createPortal нельзя вызвать на сервере с document.body. Для SSR рендерят портал только после монтирования (как выше) или используют библиотеки, которые это учитывают.

Порталы или нативные решения

ЗадачаВариант
Модальное окно<dialog> + showModal(): top layer, Esc, inert фона, возврат фокуса — без портала
Меню, всплывашка без затемненияPopover API (popover, popovertarget)
Тултип с позиционированием у элементаFloating UI / CSS Anchor Positioning + портал при необходимости
Тосты в углу экранаПортал в общий контейнер
Встроить React-виджет в чужую страницуПортал в существующий DOM-узел

Headless-библиотеки (Radix, React Aria, Base UI) используют порталы внутри и уже решают фокус, Esc и доступность.

Доступность

Портал меняет только место в DOM, а не поведение. Модалке всё равно нужны: role="dialog", aria-modal, имя (aria-labelledby), перенос фокуса внутрь, удержание фокуса, закрытие по Esc, возврат фокуса на кнопку-триггер и блокировка фона (inert на корне приложения). Нативный <dialog> даёт это бесплатно.

Что важно помнить

  • Портал = другое место в DOM, то же место в дереве React.
  • Контекст и состояние доступны, события всплывают по React-дереву.
  • На сервере — рендерить после монтирования.
  • Для модалок сначала рассмотри <dialog>, для меню — Popover API.

Мини-шпаргалка

createPortal(jsx, document.body)
Цели: overflow/z-index/transform родителя
Контекст ✔, события всплывают по React ✔
SSR: рендер после useEffect
a11y: role, aria-modal, фокус, Esc, inert
Альтернативы: <dialog>, Popover API

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам