Need help with react-keep-alive?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

StructureBuilder
598 Stars 73 Forks MIT License 101 Commits 42 Opened issues

Description

A component that maintains component state and avoids repeated re-rendering.

Services available

!
?

Need anything else?

Contributors list

No Data

React Keep Alive

npm Travis (.org) LICENSE npm bundle size (minified + gzip) downloads typescript

A component that maintains component state and avoids repeated re-rendering.

English | 中文

✨ Features

  • Not based on React Router, so you can use it wherever you need to cache it.
  • You can easily use to wrap your components to keep them alive.
  • Because it is not controlled by
    display: none | block
    , you can use animation.
  • You will be able to use the latest React Hooks.
  • Ability to manually control whether your components need to stay active.

📦 Installation

React Keep Alive requires React 16.3 or later, but if you use React Hooks, you must be React 16.8 or higher.

To use React Keep Alive with your React app:

npm install --save react-keep-alive

🔨 Usage

React Keep Alive provides

, you must use 
 to wrap the 
 cache to take effect.
import React from 'react';
import ReactDOM from 'react-dom';
import {
  Provider,
  KeepAlive,
} from 'react-keep-alive';
import Test from './views/Test';

ReactDOM.render( , document.getElementById('root'), );

💡 Why do you need this component?

If you've used Vue, you know that it has a very good component (keep-alive) that keeps the state of the component to avoid repeated re-rendering.

Sometimes, we want the list page to cache the page state after the list page enters the detail page. When the detail page returns to the list page, the list page is still the same as before the switch.

Oh, this is actually quite difficult to achieve, because the components in React cannot be reused once they are uninstalled. Two solutions are proposed in issue #12039. By using the style switch component display (

display: none | block;
), this can cause problems, such as when you switch components, you can't use animations; or use data flow management tools like Mobx and Redux, but this is too much trouble.

In the end, I implemented this effect through the React.createPortal API.

react-keep-alive
has two main components
 and 
. The 
 is responsible for saving the component's cache and rendering the cached component outside of the application via the React.createPortal API before processing. The cached components must be placed in 
, and 
 will mount the components that are cached outside the application to the location that really needs to be displayed.

📝 API Reference

Provider

Since the cached components need to be stored, the

 must be rendered at the top of the application for the program to run properly.

Props

include
: Only components that match key will be cached. It can be a string, an array of strings, or a regular expression, eg:
JavaScript
...
// or
...
// or
...

exclude
: Any component that matches key will not be cached. It can be a string, an array of strings, or a regular expression.

max
(
v2.5.2+
): If the maximum value is set, the value in the cache is deleted after it goes out.

Example

In the example below, the component is our root-level component. This means it’s at the very top of our component hierarchy.

import React from 'react';
import ReactDOM from 'react-dom';
import { Provider } from 'react-keep-alive';
import App from './App';

ReactDOM.render( , document.getElementById('root'), );

Usage with React Router and Mobx React
import React from 'react';
import ReactDOM from 'react-dom';
import {
  BrowserRouter as Router,
} from 'react-router-dom';
import {
  Provider as MobxProvider,
} from 'mobx-react';
import {
  Provider as KeepAliveProvider,
} from 'react-keep-alive';

ReactDOM.render( , document.getElementById('root'), );

Note: You must put in and the React Router must be sure to be the latest version. Because React Keep Alive uses the new Context, you must ensure that the Router does the same. Please use the following command to install the latest version.

npm install [email protected] [email protected]

KeepAlive

Children of

 will be cached, but we have to make sure that 
 is inside 
.

Props

name
: Name must exist and need to ensure that all
 names under the current 
 are unique(1.2.0 added, Replace key).

disabled
: When we don't need components for caching, we can disable it; the disabled configuration will only takes effect when the component's status changes from unactive to active.

extra
(
v2.0.1+
): Additional data can be obtained through
bindLifecycle
.

Note:

 The innermost outer layer of the packaged component must have a real DOM tag.

Example

import React from 'react';
import ReactDOM from 'react-dom';
import {
  BrowserRouter as Router,
  Switch,
  Route,
  Link,
} from 'react-router-dom';
import {
  Provider,
  KeepAlive,
} from 'react-keep-alive';

class One extends React.Component { render() { return ( // a real DOM tag

This is One.
); } }

class App extends React.Component { render() { return (

); } }

ReactDOM.render( , document.getElementById('root'), );

Usage with
include
props of

import React from 'react';
import ReactDOM from 'react-dom';
import {
  BrowserRouter as Router,
  Switch,
  Route,
  Link,
} from 'react-router-dom';
import {
  Provider,
  KeepAlive,
} from 'react-keep-alive';

class One extends React.Component { render() { return (

This is One.
); } }

class App extends React.Component { render() { return (

); } }

ReactDOM.render( , document.getElementById('root'), );

Note: If you want to use the lifecycle, wrap the components in a

bindLifecycle
high-level component.

bindLifecycle

Components that pass this high-level component wrap will have the correct lifecycle, and we have added two additional lifecycles,

componentDidActivate
and
componentWillUnactivate
.

Lifecycle after adding: Lifecycle after adding

componentDidActivate
will be executed once after the initial mount or from the unactivated state to the active state. although we see
componentDidActivate
after
componentDidUpdate
in the
Updating
phase, this does not mean
componentDidActivate
Always triggered.

At the same time, only one of the lifecycles of

componentWillUnactivate
and
componentWillUnmount
is triggered.
componentWillUnactivate
is executed when caching is required;
componentWillUnmount
is executed without caching.

Example

import React from 'react';
import {bindLifecycle} from 'react-keep-alive';

@bindLifecycle class Test extends React.Component { render() { return (

This is Test.
); } }

useKeepAliveEffect

useKeepAliveEffect
will fire when the component enters and leaves; because the component will not be unmounted while it is still active, so if you use
useEffect
, that will not achieve the real purpose.

Note:

useKeepAliveEffect
uses the latest React Hooks, so you must make sure React is the latest version.

Example

import React from 'react';
import {useKeepAliveEffect} from 'react-keep-alive';

function Test() { useKeepAliveEffect(() => { console.log("mounted"); return () => { console.log("unmounted"); }; }); return (

This is Test.
); }

🐛 Issues

If you find a bug, please file an issue on our issue tracker on GitHub.

🏁 Changelog

Changes are tracked in the CHANGELOG.md.

📄 License

React Keep Alive is available under the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.