Basic Concepts of the Portal API
Role of Portals
Typically, React components are rendered into the DOM according to the component tree hierarchy, with child elements rendered within their parent component’s DOM node. However, there are cases where you need to render a child component to an arbitrary location on the page, or even into a completely different component tree. This is where Portals come into play.
Creating a Portal
Portals are created using the ReactDOM.createPortal() function, which accepts two arguments: the React child element to render (which can be any renderable React element, such as an element, string, or fragment) and the DOM node where the child element will be inserted.
ReactDOM.createPortal(
child,
container
);Portal Usage Examples
Basic Example
Consider a modal dialog component that should render at the top level of the page, rather than within the current component tree.
// Modal.js
import React from 'react';
import ReactDOM from 'react-dom';
const modalRoot = document.getElementById('modal-root');
const Modal = ({ children }) => {
return ReactDOM.createPortal(
<div id="modal">
{children}
</div>,
modalRoot
);
};
export default Modal;In the main application, you can use this modal dialog as follows:
// App.js
import React from 'react';
import Modal from './Modal';
function App() {
return (
<div>
<button onClick={() => showModal()}>
Open Modal
</button>
<Modal>
This is a modal dialog.
</Modal>
</div>
);
}
// Assume showModal() controls the display and hiding of the ModalPortal Lifecycle
Components within a Portal follow React’s lifecycle. Even when rendered elsewhere on the page, lifecycle methods like componentDidMount and componentWillUnmount are still invoked.
Advanced Portal Usage
Using Portals in Functional Components
In functional components, import the createPortal function from react-dom.
// Modal.js
import React from 'react';
import { createPortal } from 'react-dom';
const modalRoot = document.getElementById('modal-root');
const Modal = ({ children }) => {
return createPortal(
<div id="modal">
{children}
</div>,
modalRoot
);
};
export default Modal;Portals and State Management
When using state in a Portal, ensure state updates don’t trigger a full page re-render, as Portal content is isolated from the rest of the page.
// Modal.js
import React, { useState } from 'react';
import { createPortal } from 'react-dom';
const modalRoot = document.getElementById('modal-root');
const Modal = () => {
const [isOpen, setIsOpen] = useState(false);
return createPortal(
isOpen && (
<div id="modal">
<button onClick={() => setIsOpen(false)}>
Close Modal
</button>
</div>
),
modalRoot
);
};
export default Modal;Portal Considerations
Portals and Style Isolation
Since Portal content may reside in a different part of the DOM tree, careful handling of CSS styles is necessary. Using CSS Modules or Scoped CSS can help prevent style conflicts.
Portals and Event Bubbling
Event handling in Portals works the same as in regular components. However, events may need to traverse multiple component trees, so you may need to adjust event listener bindings accordingly.
Portal Application Scenarios
Modal Dialogs
Modal dialogs are the most common use case for Portals, as they typically need to overlay the entire page, regardless of the current component hierarchy.
Tooltips and Pop-up Menus
Tooltips and pop-up menus often need to be positioned relative to the mouse pointer or triggering element. Portals can avoid layout issues in these cases.
Fixed Headers or Footers
Fixed headers or footers can be rendered to the top or bottom of the page via Portals without affecting the layout of other components.



