https://github.com/donavon/use-cached-state
https://github.com/donavon/use-cached-state
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/donavon/use-cached-state
- Owner: donavon
- License: mit
- Created: 2019-05-01T10:07:43.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-01-17T13:03:55.000Z (over 3 years ago)
- Last Synced: 2025-02-01T01:11:25.654Z (8 months ago)
- Language: JavaScript
- Size: 220 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# use-cached-state
A cached and optionally persisted alternative to useState.
[](https://badge.fury.io/js/use-cached-state)
## Features
💰 Caches state values even after your component unmounts.
💰 Optionally persists to `localStorage`.
💰 Shares values between components on the same page and even in different browser tabs!
## Installation
```bash
$ npm i use-cached-state
```
or
```bash
$ yarn add use-cached-state
```
## Usage
Here is a basic setup. Perform the following from within your module, but not in your component.
This will create a custom Hook that you can then use in your component.
```js
const useCachedState = createCachedState(config);
```
Next, from without your component, do this (instead of `useState`).
```js
const [state, setState] = useCachedState(options);
```
### Parameters
`createCachedState` is passed a single config object with the following properties.
| Parameter | Description |
| :---------- | :---------------------------------------------------------------------------------------------- |
| `namespace` | A required string that will be used as a namespace. |
| `storageProvider` | A storage provider to use. The default is `null` which specifies NOT to persist to storage (i.e. just cache in memory). The storage provider must provide a `getItem` and a `setItem` method. You may use `localStorage` or `sessionStorage` or your own custom storage provider. |
### Return
`createCachedState` returns a custom Hook that you can use from within your component. This custom Hook accepts an options object with the following properties.
| Property | Description |
| :------------- | :--------------------- |
| `name` | A optional string that represents the name to use for this instance of the component. If all instances are to share the same state, pass the same name (or use the default). |
| `initialValue` | This will be the initial value used. |
## Example
In this example, we replace `useState` with a call to `useCachedCounterState`.
This gives us the same state functionality, but it also persists to `localstorage`.
```js
const useCachedCounterState = createCachedState({
namespace: 'counter',
storageProvider: localStorage,
});
const CountButton = ({ name, initialValue }) => {
const [count, setCount] = useCachedCounterState({
name,
initialValue,
});
const increment = () => setCount(c => c + 1);
return (
Click Me: {count}
);
};
```
### Live demo
You can view/edit the sample code above on CodeSandbox.
[](https://codesandbox.io/s/10kj4n30j7)
## Prior art
This is the next generation of my own [`use-persisted-state`](https://github.com/donavon/use-persisted-state/)
package.
It was inspired by [a tweet](https://twitter.com/ryanflorence/status/1111402632218734593)
from Ryan Florence.
## License
**[MIT](LICENSE)** Licensed
## Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Donavon West
🤔 🚇 🚧 👀 💻 🎨
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!