Порталы: 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