react.dev/content/docs/portals.md

---
id: portals
title: Portals
permalink: docs/portals.html
---

Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.

```js
ReactDOM.createPortal(child, container)
```

The first argument (`child`) is any [renderable React child](/docs/react-component.html#render), such as an element, string, or fragment. The second argument (`container`) is a DOM element.

## Usage

Normally, when you return an element from a component's render method, it's mounted into the DOM as a child of the nearest parent node:

```js{4,6}
render() {
  // React mounts a new div and renders the children into it
  return (
    <div>
      {this.props.children}
    </div>
  );
}
```

However, sometimes it's useful to insert a child into a different location in the DOM:

```js{6}
render() {
  // React does *not* create a new div. It renders the children into `domNode`.
  // `domNode` is any valid DOM node, regardless of its location in the DOM.
  return ReactDOM.createPortal(
    this.props.children,
    domNode
  );
}
```

A typical use case for portals is when a parent component has an `overflow: hidden` or `z-index` style, but you need the child to visually "break out" of its container. For example, dialogs, hovercards, and tooltips.

> Note:
>
> When working with portals, remember that [managing keyboard focus](/docs/accessibility.html#programmatically-managing-focus) becomes very important.
>
> For modal dialogs, ensure that everyone can interact with them by following the [WAI-ARIA Modal Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal).

[**Try it on CodePen**](https://codepen.io/gaearon/pen/yzMaBd)

## Event Bubbling Through Portals

Even though a portal can be anywhere in the DOM tree, it behaves like a normal React child in every other way. Features like context work exactly the same regardless of whether the child is a portal, as the portal still exists in the *React tree* regardless of position in the *DOM tree*.

This includes event bubbling. An event fired from inside a portal will propagate to ancestors in the containing *React tree*, even if those elements are not ancestors in the *DOM tree*. Assuming the following HTML structure:

```html
<html>
  <body>
    <div id="app-root"></div>
    <div id="modal-root"></div>
  </body>
</html>
```

A `Parent` component in `#app-root` would be able to catch an uncaught, bubbling event from the sibling node `#modal-root`.

```js{28-31,42-49,53,61-63,70-71,74}
// These two containers are siblings in the DOM
const appRoot = document.getElementById('app-root');
const modalRoot = document.getElementById('modal-root');

class Modal extends React.Component {
  constructor(props) {
    super(props);
    this.el = document.createElement('div');
  }

  componentDidMount() {
    // The portal element is inserted in the DOM tree after
    // the Modal's children are mounted, meaning that children
    // will be mounted on a detached DOM node. If a child
    // component requires to be attached to the DOM tree
    // immediately when mounted, for example to measure a
    // DOM node, or uses 'autoFocus' in a descendant, add
    // state to Modal and only render the children when Modal
    // is inserted in the DOM tree.
    modalRoot.appendChild(this.el);
  }

  componentWillUnmount() {
    modalRoot.removeChild(this.el);
  }

  render() {
    return ReactDOM.createPortal(
      this.props.children,
      this.el,
    );
  }
}

class Parent extends React.Component {
  constructor(props) {
    super(props);
    this.state = {clicks: 0};
    this.handleClick = this.handleClick.bind(this);
  }

  handleClick() {
    // This will fire when the button in Child is clicked,
    // updating Parent's state, even though button
    // is not direct descendant in the DOM.
    this.setState(state => ({
      clicks: state.clicks + 1
    }));
  }

  render() {
    return (
      <div onClick={this.handleClick}>
        <p>Number of clicks: {this.state.clicks}</p>
        <p>
          Open up the browser DevTools
          to observe that the button
          is not a child of the div
          with the onClick handler.
        </p>
        <Modal>
          <Child />
        </Modal>
      </div>
    );
  }
}

function Child() {
  // The click event on this button will bubble up to parent,
  // because there is no 'onClick' attribute defined
  return (
    <div className="modal">
      <button>Click</button>
    </div>
  );
}

ReactDOM.render(<Parent />, appRoot);
```

[**Try it on CodePen**](https://codepen.io/gaearon/pen/jGBWpE)

Catching an event bubbling up from a portal in a parent component allows the development of more flexible abstractions that are not inherently reliant on portals. For example, if you render a `<Modal />` component, the parent can capture its events regardless of whether it's implemented using portals.
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			`---`
			`id: portals`
			`title: Portals`
			`permalink: docs/portals.html`
			`---`

			`Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.`

			```js
			`ReactDOM.createPortal(child, container)`
			```

Add new docs website (#10896) Adds a new docs website, built with Gatsby JS, to replace the old Jekyll site. Source code for the new site lives in /www (although markdown and YML data still comes from the legacy /docs folder). Changes to either markdown or website source code can be previewed on Netlify. The react-js bot should automatically add comments to each PR with preview links. (This preview is generated by running the newly-added yarn build:docs command in the root package.json.) The majority of the changes in this PR are contained within the new /www directory. However some minor modifications have been made to existing content in the /docs directory: * Modified frontmatter author block to always be an array * Small markdown formatting tweaks 7 years ago			The first argument (`child`) is any [renderable React child](/docs/react-component.html#render), such as an element, string, or fragment. The second argument (`container`) is a DOM element.
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
revert id adding 6 years ago			`## Usage`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
			`Normally, when you return an element from a component's render method, it's mounted into the DOM as a child of the nearest parent node:`

			```js{4,6}
			`render() {`
			`// React mounts a new div and renders the children into it`
			`return (`
			`<div>`
			`{this.props.children}`
			`</div>`
			`);`
			`}`
			```

			`However, sometimes it's useful to insert a child into a different location in the DOM:`

			```js{6}
			`render() {`
			// React does not create a new div. It renders the children into `domNode`.
			// `domNode` is any valid DOM node, regardless of its location in the DOM.
React.createPortal is not a function (#10843) 7 years ago			`return ReactDOM.createPortal(`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			`this.props.children,`
Remove trailing comma 7 years ago			`domNode`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			`);`
			`}`
			```

			A typical use case for portals is when a parent component has an `overflow: hidden` or `z-index` style, but you need the child to visually "break out" of its container. For example, dialogs, hovercards, and tooltips.

			`> Note:`
			`>`
Add accessibility guidelines link to portals doc (#846) * Add accessibility guidelines link to portals doc * Add more detail to portal accessibility note * Clarify text using suggested content 7 years ago			`> When working with portals, remember that [managing keyboard focus](/docs/accessibility.html#programmatically-managing-focus) becomes very important.`
			`>`
			`> For modal dialogs, ensure that everyone can interact with them by following the [WAI-ARIA Modal Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal).`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
Make CodePen links more prominent and consistent 7 years ago			`[Try it on CodePen](https://codepen.io/gaearon/pen/yzMaBd)`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
revert id adding 6 years ago			`## Event Bubbling Through Portals`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
Update Portals Documentation (#10840) * Update Portals Documentation Correct some grammar to be more explicit and clear. Update example CodePen to better match code found in documentation. Update code example styles to match other code examples (ie. 'State and Lifecycle', 'Handling Events'). * Clean up comment to be accurate to example There was a small comment overlooked when reviewing the documentation. This fixes it to be accurate to the example as well as grammatically correct. * Update portals.md * More fixes 7 years ago			`Even though a portal can be anywhere in the DOM tree, it behaves like a normal React child in every other way. Features like context work exactly the same regardless of whether the child is a portal, as the portal still exists in the React tree regardless of position in the DOM tree.`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
Update Portals Documentation (#10840) * Update Portals Documentation Correct some grammar to be more explicit and clear. Update example CodePen to better match code found in documentation. Update code example styles to match other code examples (ie. 'State and Lifecycle', 'Handling Events'). * Clean up comment to be accurate to example There was a small comment overlooked when reviewing the documentation. This fixes it to be accurate to the example as well as grammatically correct. * Update portals.md * More fixes 7 years ago			`This includes event bubbling. An event fired from inside a portal will propagate to ancestors in the containing React tree, even if those elements are not ancestors in the DOM tree. Assuming the following HTML structure:`

			```html
			`<html>`
			`<body>`
			`<div id="app-root"></div>`
			`<div id="modal-root"></div>`
			`</body>`
			`</html>`
			```

Update docs for React 16 (#10846) 7 years ago			A `Parent` component in `#app-root` would be able to catch an uncaught, bubbling event from the sibling node `#modal-root`.
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
Add warning about Modal children mounting detached from DOM tree 7 years ago			```js{28-31,42-49,53,61-63,70-71,74}
Update docs for React 16 (#10846) 7 years ago			`// These two containers are siblings in the DOM`
Update Portals Documentation (#10840) * Update Portals Documentation Correct some grammar to be more explicit and clear. Update example CodePen to better match code found in documentation. Update code example styles to match other code examples (ie. 'State and Lifecycle', 'Handling Events'). * Clean up comment to be accurate to example There was a small comment overlooked when reviewing the documentation. This fixes it to be accurate to the example as well as grammatically correct. * Update portals.md * More fixes 7 years ago			`const appRoot = document.getElementById('app-root');`
			`const modalRoot = document.getElementById('modal-root');`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
Update docs for React 16 (#10846) 7 years ago			`class Modal extends React.Component {`
			`constructor(props) {`
			`super(props);`
			`this.el = document.createElement('div');`
			`}`

			`componentDidMount() {`
Add warning about Modal children mounting detached from DOM tree 7 years ago			`// The portal element is inserted in the DOM tree after`
			`// the Modal's children are mounted, meaning that children`
			`// will be mounted on a detached DOM node. If a child`
			`// component requires to be attached to the DOM tree`
			`// immediately when mounted, for example to measure a`
			`// DOM node, or uses 'autoFocus' in a descendant, add`
			`// state to Modal and only render the children when Modal`
			`// is inserted in the DOM tree.`
Update docs for React 16 (#10846) 7 years ago			`modalRoot.appendChild(this.el);`
			`}`

			`componentWillUnmount() {`
			`modalRoot.removeChild(this.el);`
			`}`

			`render() {`
			`return ReactDOM.createPortal(`
Add warning about Modal children mounting detached from DOM tree 7 years ago			`this.props.children,`
Update docs for React 16 (#10846) 7 years ago			`this.el,`
			`);`
			`}`
			`}`

Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			`class Parent extends React.Component {`
Update Portals Documentation (#10840) * Update Portals Documentation Correct some grammar to be more explicit and clear. Update example CodePen to better match code found in documentation. Update code example styles to match other code examples (ie. 'State and Lifecycle', 'Handling Events'). * Clean up comment to be accurate to example There was a small comment overlooked when reviewing the documentation. This fixes it to be accurate to the example as well as grammatically correct. * Update portals.md * More fixes 7 years ago			`constructor(props) {`
			`super(props);`
			`this.state = {clicks: 0};`
			`this.handleClick = this.handleClick.bind(this);`
			`}`

			`handleClick() {`
Update docs for React 16 (#10846) 7 years ago			`// This will fire when the button in Child is clicked,`
			`// updating Parent's state, even though button`
			`// is not direct descendant in the DOM.`
Change name of setState updater first arg to 'state' (#1155) 6 years ago			`this.setState(state => ({`
			`clicks: state.clicks + 1`
Update Portals Documentation (#10840) * Update Portals Documentation Correct some grammar to be more explicit and clear. Update example CodePen to better match code found in documentation. Update code example styles to match other code examples (ie. 'State and Lifecycle', 'Handling Events'). * Clean up comment to be accurate to example There was a small comment overlooked when reviewing the documentation. This fixes it to be accurate to the example as well as grammatically correct. * Update portals.md * More fixes 7 years ago			`}));`
			`}`

Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			`render() {`
			`return (`
Update docs for React 16 (#10846) 7 years ago			`<div onClick={this.handleClick}>`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			`<p>Number of clicks: {this.state.clicks}</p>`
Update docs for React 16 (#10846) 7 years ago			`<p>`
			`Open up the browser DevTools`
			`to observe that the button`
Minor update to portals docs "child" language (#10870) * Update portals docs "child" language This commit changes the portals docs so that the language of the Parent no longer feels like it is missing a word with "is not a child the div with onClick handler" and replaces that with "is not a direct child of the div with the onClick handler". closes #10868 * Update portals.md 7 years ago			`is not a child of the div`
			`with the onClick handler.`
Update docs for React 16 (#10846) 7 years ago			`</p>`
			`<Modal>`
			`<Child />`
			`</Modal>`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			`</div>`
			`);`
			`}`
			`}`

			`function Child() {`
Update Portals Documentation (#10840) * Update Portals Documentation Correct some grammar to be more explicit and clear. Update example CodePen to better match code found in documentation. Update code example styles to match other code examples (ie. 'State and Lifecycle', 'Handling Events'). * Clean up comment to be accurate to example There was a small comment overlooked when reviewing the documentation. This fixes it to be accurate to the example as well as grammatically correct. * Update portals.md * More fixes 7 years ago			`// The click event on this button will bubble up to parent,`
			`// because there is no 'onClick' attribute defined`
			`return (`
			`<div className="modal">`
			`<button>Click</button>`
			`</div>`
			`);`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			`}`

Update Portals Documentation (#10840) * Update Portals Documentation Correct some grammar to be more explicit and clear. Update example CodePen to better match code found in documentation. Update code example styles to match other code examples (ie. 'State and Lifecycle', 'Handling Events'). * Clean up comment to be accurate to example There was a small comment overlooked when reviewing the documentation. This fixes it to be accurate to the example as well as grammatically correct. * Update portals.md * More fixes 7 years ago			`ReactDOM.render(<Parent />, appRoot);`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago			```

Make CodePen links more prominent and consistent 7 years ago			`[Try it on CodePen](https://codepen.io/gaearon/pen/jGBWpE)`
Doc updates for React 16 + blog post (#10824) * Doc updates for React 16 + blog post * Add link to Sophie's post 7 years ago
Update Portals Documentation (#10840) * Update Portals Documentation Correct some grammar to be more explicit and clear. Update example CodePen to better match code found in documentation. Update code example styles to match other code examples (ie. 'State and Lifecycle', 'Handling Events'). * Clean up comment to be accurate to example There was a small comment overlooked when reviewing the documentation. This fixes it to be accurate to the example as well as grammatically correct. * Update portals.md * More fixes 7 years ago			Catching an event bubbling up from a portal in a parent component allows the development of more flexible abstractions that are not inherently reliant on portals. For example, if you render a `<Modal />` component, the parent can capture its events regardless of whether it's implemented using portals.