react-portal
Advanced tools
Comparing version 3.1.0 to 4.0.0-beta.1
{ | ||
"name": "react-portal", | ||
"version": "3.1.0", | ||
"description": "React component for transportation of modals, lightboxes, loading bars... to document.body", | ||
"main": "build/portal", | ||
"version": "4.0.0-beta.1", | ||
"description": "To make your life with React Portals easier.", | ||
"main": "lib/index.js", | ||
"module": "es/index.js", | ||
"jsnext:main": "es/index.js", | ||
"files": [ | ||
@@ -10,3 +12,3 @@ "*.md", | ||
"lib", | ||
"build" | ||
"es" | ||
], | ||
@@ -20,10 +22,10 @@ "repository": { | ||
"scripts": { | ||
"start": "node devServerIndex.js", | ||
"build": "mkdir -p build && babel ./lib/portal.js --out-file ./build/portal.js", | ||
"build:examples": "npm run clean && npm run build:examples:webpack", | ||
"build:examples:webpack": "cross-env NODE_ENV=production webpack --config webpack.config.prod.babel.js", | ||
"clean": "rimraf build", | ||
"test": "mocha", | ||
"lint": "mocha test/eslint_spec.js", | ||
"prepublish": "cross-env NODE_ENV=production npm run build" | ||
"build": "npm run build-es && npm run build-cjs", | ||
"build-es": "babel ./src --out-dir ./es", | ||
"build-cjs": "BABEL_ENV=commonjs babel ./src --out-dir ./lib", | ||
"build:examples": "cross-env webpack", | ||
"prepublish": "cross-env NODE_ENV=production npm run build", | ||
"lint": "eslint webpack.config.js src/**/*.js", | ||
"format": "prettier --write \"**/*.js\"", | ||
"test": "cross-env BABEL_ENV=commonjs jest" | ||
}, | ||
@@ -42,36 +44,28 @@ "tags": [ | ||
], | ||
"dependencies": { | ||
"prop-types": "^15.5.8" | ||
}, | ||
"devDependencies": { | ||
"babel-cli": "^6.8.0", | ||
"babel-core": "^6.8.0", | ||
"babel-eslint": "^6.0.4", | ||
"babel-loader": "^6.2.1", | ||
"babel-plugin-add-module-exports": "^0.2.1", | ||
"babel-eslint": "^7.2.3", | ||
"babel-loader": "^7.1.1", | ||
"babel-plugin-transform-es2015-modules-commonjs": "^6.24.1", | ||
"babel-plugin-transform-object-rest-spread": "^6.23.0", | ||
"babel-preset-es2015": "^6.3.13", | ||
"babel-preset-react": "^6.3.13", | ||
"babel-preset-react-hmre": "^1.0.1", | ||
"babel-register": "^6.8.0", | ||
"cross-env": "^1.0.7", | ||
"cross-env": "^5.0.1", | ||
"enzyme": "^2.3.0", | ||
"eslint": "^2.9.0", | ||
"eslint-config-airbnb": "^9.0.1", | ||
"eslint-plugin-import": "^1.8.0", | ||
"eslint-plugin-jsx-a11y": "^1.2.0", | ||
"eslint-plugin-react": "^5.1.1", | ||
"express": "^4.13.3", | ||
"jsdom": "^9.0.0", | ||
"mocha": "^2.3.4", | ||
"mocha-eslint": "^2.0.2", | ||
"react": "^15.2.0", | ||
"react-addons-test-utils": "^15.2.0", | ||
"react-dom": "^15.2.0", | ||
"eslint": "^4.3.0", | ||
"eslint-plugin-prettier": "^2.1.2", | ||
"jest": "^20.0.4", | ||
"prettier": "^1.5.3", | ||
"react": "^16.0.0", | ||
"react-dom": "^16.0.0", | ||
"rimraf": "^2.5.0", | ||
"sinon": "^1.17.4", | ||
"tween.js": "^16.3.1", | ||
"webpack": "^1.13.0", | ||
"webpack-dev-middleware": "^1.6.1", | ||
"webpack-hot-middleware": "^2.6.0" | ||
"webpack": "^3.4.1" | ||
}, | ||
"dependencies": { | ||
"prop-types": "^15.5.8" | ||
"peerDependencies": { | ||
"react": "^16.0.0-0 || ^17.0.0-0" | ||
} | ||
} |
198
README.md
@@ -7,171 +7,115 @@ React-portal | ||
> Struggling with modals, lightboxes or loading bars in React? React-portal creates a new top-level React tree and injects its child into it. That's necessary for proper styling (especially positioning). | ||
> Struggling with modals, lightboxes or loading bars in React? React-portal creates a new top-level React tree and injects its children into it. That's necessary for proper styling (especially positioning). | ||
*This is documentation for React-portal v4+ (currently beta). It works only with React v16+. For v3, please check [this document](READMEv3.MD). The final API can change. The test suite needs to be rebuilt.* | ||
## Features | ||
- transports its child into a new React component and appends it to the **document.body** (creates a new independent React tree) | ||
- can be opened by the prop **isOpened** | ||
- can be opened after a click on an element that you pass through the prop **openByClickOn** (and then it takes care of the open/close state) | ||
- doesn't leave any mess in DOM after closing | ||
- provides its child with **this.props.closePortal** callback | ||
- transports its children into a new React Portal which is appended by default to **document.body** | ||
- can target user specified DOM element | ||
- supports server-side rendering | ||
- **uses React v16 and its official API for creating portals** | ||
- supports returning arrays (no wrapper divs needed) | ||
- `<Portal />` and `<PortalWithState />` so there is no compromise between flexibility and convenience | ||
- doesn't produce any DOM mess | ||
- provides **close on ESC** and **close on outside mouse click** out of the box | ||
- supports absolute positioned components (great for tooltips) | ||
- **no dependencies** | ||
- **fully covered by tests** | ||
- **no dependencies**, minimalistic | ||
## Demo | ||
Try [https://miksu.cz/react-portal](https://miksu.cz/react-portal) **or** | ||
```shell | ||
git clone https://github.com/tajo/react-portal | ||
cd react-portal | ||
npm install | ||
npm run build:examples | ||
open examples/index.html | ||
``` | ||
## Installation | ||
```shell | ||
npm install react react-dom react-portal --save | ||
yarn add react react-dom react-portal@next | ||
``` | ||
## Usage | ||
```jsx | ||
import React from 'react'; | ||
import ReactDOM from 'react-dom'; | ||
import Portal from 'react-portal'; | ||
export default class App extends React.Component { | ||
### Portal | ||
render() { | ||
const button1 = <button>Open portal with pseudo modal</button>; | ||
```jsx | ||
import { Portal } from 'react-portal'; | ||
return ( | ||
<Portal closeOnEsc closeOnOutsideClick openByClickOn={button1}> | ||
<PseudoModal> | ||
<h2>Pseudo Modal</h2> | ||
<p>This react component is appended to the document body.</p> | ||
</PseudoModal> | ||
</Portal> | ||
); | ||
} | ||
<Portal> | ||
This text is portaled at the end of document.body! | ||
</Portal> | ||
} | ||
<Portal node={document && document.getElementById('san-francisco')}> | ||
This text is portaled into San Francisco! | ||
</Portal> | ||
``` | ||
export class PseudoModal extends React.Component { | ||
That's it! Do you want to toggle portal? It's a plain React component, so you can simply do: | ||
render() { | ||
return ( | ||
<div> | ||
{this.props.children} | ||
<p><button onClick={this.props.closePortal}>Close this</button></p> | ||
</div> | ||
); | ||
} | ||
} | ||
ReactDOM.render(<App />, document.getElementById('react-body')); | ||
```jsx | ||
{isOpen && <Portal>Sometimes portaled?</Portal>} | ||
``` | ||
## Documentation - props | ||
### Always required | ||
**This gives you absolute flexibility and control**. But what if you typically use React-portal just to open modals and you want to cut some boilerplate? In other words, **you are ok with giving up some flexibility for convenience**. Let React-portal handle its own state! | ||
#### children : ReactElement | ||
The portal expects one child (`<Portal><Child ... /></Portal>`) that will be ported. | ||
### PortalWithState | ||
### One of these two required | ||
```jsx | ||
import { PortalWithState } from 'react-portal'; | ||
#### isOpened : bool | ||
If true, the portal is open. If false, the portal is closed. It's up to you to take care of the closing (aka taking care of the state). Don't use this prop if you want to make your life easier. Use openByClickOn instead! | ||
<PortalWithState closeOnOutsideClick closeOnEsc> | ||
{({ openPortal, closePortal, isOpen, portal }) => [ | ||
!isOpen && <button onClick={openPortal}>Open Portal</button>, | ||
portal( | ||
<p> | ||
This is more advanced Portal. It handles its own state. | ||
<button onClick={closePortal}>Close me!</button>, hit ESC or | ||
click outside of me. | ||
</p> | ||
) | ||
]} | ||
</PortalWithState> | ||
``` | ||
#### openByClickOn : ReactElement | ||
The second way how to open the portal. This element will be rendered by the portal immediately | ||
with `onClick` handler that triggers portal opening. **How to close the portal then?** The portal provides its ported child with a callback `this.props.closePortal`. Or you can use built-in portal closing methods (closeOnEsc, ... more below). Notice that you don't have to deal with the open/close state (like when using the `isOpened` prop). | ||
Don't let this example to intimidate you! `PortalWithState` **expects one child, a function**. This function gets a few parameters (mostly functions) and returns a React component. | ||
### Optional | ||
### There are 4 optional parameters: | ||
#### closeOnEsc: bool | ||
If true, the portal can be closed by the key ESC. | ||
- **openPortal** - function that you can call to open the portal | ||
- **closePortal** - function that you can call to close the portal | ||
- **portal** - the part of component that should be portaled needs to be wrapped by this function | ||
- **isOpen** - boolean, tells you if portal is open/closed | ||
#### closeOnOutsideClick: bool | ||
If true, the portal can be closed by the outside mouse click. | ||
### `<PortalWithState />` accepts this optional props: | ||
#### onOpen: func(DOMNode) | ||
This callback is called when the portal is opened and rendered (useful for animating the DOMNode). | ||
- **node** - same as `<Portal>`, you can target a custom DOM element | ||
- **closeOnOutsideClick** - boolean, portal closes when you click outside of it | ||
- **closeOnEsc** - boolean, portal closes when the ESC key is hit | ||
- **defaultOpen** - boolean, the starting state of portal is being open | ||
- **onOpen** - function, will get triggered after portal is open | ||
- **onClose** - function, will get triggered after portal is closed | ||
#### beforeClose: func(DOMNode, removeFromDOM) | ||
This callback is called when the closing event is triggered but it prevents normal removal from the DOM. So, you can do some DOMNode animation first and then call removeFromDOM() that removes the portal from DOM. | ||
Also notice, that **the example returns an array since React v16 supports it**! You can also return a single component. In that case, the example would be wrapped by a div as you were used to. | ||
#### onClose: func | ||
This callback is called when the portal closes and after beforeClose. | ||
## Run Examples | ||
#### onUpdate: func | ||
This callback is called when the portal is (re)rendered. | ||
## Tips & Tricks | ||
- Does your modal have a fullscreen overlay and the `closeOnOutsideClick` doesn't work? [There is a simple solution](https://github.com/tajo/react-portal/issues/2#issuecomment-92058826). | ||
- Does your inner inner component `<LevelTwo />` | ||
```jsx | ||
<Portal> | ||
<LevelOne> | ||
<LevelTwo /> | ||
</LevelOne> | ||
</Portal> | ||
```shell | ||
git clone https://github.com/tajo/react-portal | ||
cd react-portal | ||
yarn install | ||
yarn build:examples | ||
open examples/index.html | ||
``` | ||
also need an access to `this.props.closePortal()`? You can't just use `{this.props.children}` in render method of `<LevelOne>` component. You have to clone it instead: | ||
## Contributions Welcome! | ||
```jsx | ||
{React.cloneElement( | ||
this.props.children, | ||
{closePortal: this.props.closePortal} | ||
)} | ||
``` | ||
#### Open modal programmatically | ||
Sometimes you need to open your portal (e.g. modal) automatically. There is no button to click on. No problem, because the portal has the `isOpened` prop, so you can just set it to `true` or `false`. However, then it's completely up to you to take care about the portal closing (ESC, outside click, no `this.props.closePortal` callback...). | ||
However, there is a nice trick how to make this happen even without `isOpened`: | ||
```jsx | ||
<Portal ref="myPortal"> | ||
<PseudoModal title="My modal"> | ||
Modal content | ||
</PseudoModal> | ||
</Portal> | ||
``` | ||
```jsx | ||
this.refs.myPortal.openPortal() | ||
// opens the portal, yay! | ||
``` | ||
## Contribution | ||
Please, create issues and pull requests. | ||
```shell | ||
git clone https://github.com/tajo/react-portal | ||
cd react-portal | ||
npm install | ||
npm start | ||
open http://localhost:3000 | ||
yarn install | ||
yarn build:examples --watch | ||
open examples/index.html | ||
``` | ||
**Don't forget to run this before every commit:** | ||
### Run Tests | ||
``` | ||
npm test | ||
yarn test | ||
``` | ||
## Credits | ||
## Author | ||
Inspired by the talk [React.js Conf 2015 - Hype!, Ryan Florence](https://www.youtube.com/watch?v=z5e7kWSHWTg) | ||
Vojtech Miksu 2015, [miksu.cz](https://miksu.cz), [@vmiksu](https://twitter.com/vmiksu) | ||
Vojtech Miksu 2017, [miksu.cz](https://miksu.cz), [@vmiksu](https://twitter.com/vmiksu) |
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
No v1
QualityPackage is not semver >=1. This means it is not stable and does not support ^ ranges.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
18
9
24292
2
362
2
121
1