You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
145 lines
4.2 KiB
145 lines
4.2 KiB
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)
|
||
|
|
```
|
||
|
|
|
||
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.
|
||
|
7 years ago
|
|
||
|
|
## 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.
|
||
7 years ago
|
return ReactDOM.createPortal(
|
||
|
7 years ago
|
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:
|
||
|
|
>
|
||
7 years ago
|
> It is important to remember, when working with portals, you'll need to make sure to follow the proper accessibility guidelines.
|
||
|
7 years ago
|
|
||
7 years ago
|
[Try it on CodePen.](https://codepen.io/gaearon/pen/yzMaBd)
|
||
|
7 years ago
|
|
||
|
7 years ago
|
## Event Bubbling Through Portals
|
||
|
7 years ago
|
|
||
|
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*.
|
||
|
7 years ago
|
|
||
|
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>
|
||
|
|
```
|
||
|
|
|
||
|
7 years ago
|
A `Parent` component in `#app-root` would be able to catch an uncaught, bubbling event from the sibling node `#modal-root`.
|
||
|
7 years ago
|
|
||
|
7 years ago
|
```js{20-23,34-41,45,53-55,62-63,66}
|
||
|
|
// These two containers are siblings in the DOM
|
||
|
7 years ago
|
const appRoot = document.getElementById('app-root');
|
||
|
|
const modalRoot = document.getElementById('modal-root');
|
||
|
7 years ago
|
|
||
|
7 years ago
|
class Modal extends React.Component {
|
||
|
|
constructor(props) {
|
||
|
|
super(props);
|
||
|
|
this.el = document.createElement('div');
|
||
|
|
}
|
||
|
|
|
||
|
|
componentDidMount() {
|
||
|
|
modalRoot.appendChild(this.el);
|
||
|
|
}
|
||
|
|
|
||
|
|
componentWillUnmount() {
|
||
|
|
modalRoot.removeChild(this.el);
|
||
|
|
}
|
||
|
|
|
||
|
|
render() {
|
||
|
|
return ReactDOM.createPortal(
|
||
|
|
this.props.children,
|
||
|
|
this.el,
|
||
|
|
);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
7 years ago
|
class Parent extends React.Component {
|
||
|
7 years ago
|
constructor(props) {
|
||
|
|
super(props);
|
||
|
|
this.state = {clicks: 0};
|
||
|
|
this.handleClick = this.handleClick.bind(this);
|
||
|
|
}
|
||
|
|
|
||
|
|
handleClick() {
|
||
|
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.
|
||
|
7 years ago
|
this.setState(prevState => ({
|
||
|
|
clicks: prevState.clicks + 1
|
||
|
|
}));
|
||
|
|
}
|
||
|
|
|
||
|
7 years ago
|
render() {
|
||
|
|
return (
|
||
|
7 years ago
|
<div onClick={this.handleClick}>
|
||
|
7 years ago
|
<p>Number of clicks: {this.state.clicks}</p>
|
||
|
7 years ago
|
<p>
|
||
|
|
Open up the browser DevTools
|
||
|
|
to observe that the button
|
||
7 years ago
|
is not a child of the div
|
||
|
|
with the onClick handler.
|
||
|
7 years ago
|
</p>
|
||
|
|
<Modal>
|
||
|
|
<Child />
|
||
|
|
</Modal>
|
||
|
7 years ago
|
</div>
|
||
|
|
);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
function Child() {
|
||
|
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>
|
||
|
|
);
|
||
|
7 years ago
|
}
|
||
|
|
|
||
|
7 years ago
|
ReactDOM.render(<Parent />, appRoot);
|
||
|
7 years ago
|
```
|
||
|
|
|
||
|
7 years ago
|
[Try it on CodePen.](https://codepen.io/gaearon/pen/jGBWpE)
|
||
|
7 years ago
|
|
||
|
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.
|