https://github.com/kyle-west/persistent-state
🔏 A native web component that holds onto the state of input elements during a session and/or between sessions.
https://github.com/kyle-west/persistent-state
html5 localstorage native persistent-storage pojo sessionstorage webcomponents
Last synced: 4 months ago
JSON representation
🔏 A native web component that holds onto the state of input elements during a session and/or between sessions.
- Host: GitHub
- URL: https://github.com/kyle-west/persistent-state
- Owner: kyle-west
- License: mit
- Created: 2018-12-27T17:32:57.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2019-08-14T18:40:19.000Z (over 6 years ago)
- Last Synced: 2025-08-28T15:21:12.233Z (4 months ago)
- Topics: html5, localstorage, native, persistent-storage, pojo, sessionstorage, webcomponents
- Language: JavaScript
- Homepage:
- Size: 170 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ``
[](https://travis-ci.com/kyle-west/persistent-state) [](https://github.com/kyle-west/persistent-state/releases/latest) [](https://github.com/kyle-west/persistent-state/blob/master/LICENSE) 
A native web component that holds onto the state of input elements during a
session and/or between sessions.
# Installation
Any of the following commands will install `persistent-state`. Just pick your
package manager.
```sh
bower install persistent-state --save
# OR
yarn add kyle-west/persistent-state
# OR
npm install kyle-west/persistent-state --save
```
# Usage
Simply import the `persistent-state.html` file to begin using. A `persistent-state.js`
file is also available if you wish to use script:src sourcing instead of HTML imports.
```html
```
Wrap your elements in a `` tag to activate. The default case
uses `localStorage` to store state which will persist information between sessions.
If you wish to only store information for a session, add the `type="session"`
attribute. For the best experience, please provide each element with an `id`.
If you have many `` elements in a DOM, it is recommended that
you provide an `id` for each `` to avoid name collisions.
```html
```
## Custom Storage Keys
Adding the `key` attribute will allow the input elements to have their values
each stored under a key computed from the given `key` and `id` attributes.
```html
```
## Supported Elements
Currently, the only supported elements are ``, ``, and `` tags.
If you have a custom element you wish to add support to, you can register it
manually with the following:
```js
new PersistentStateRegistry().registerCustomElement({
// the tag name of your custom web component
name: 'my-custom-input-element',
// this is the property that will initialize on your component with any stored values
updateProperty: 'customValue',
// [OPTIONAL] specify if the stored data should be handled as JSON (default: false)
isJSON: true,
// this is the name of the event your component fires when it's internal input value changes
changeEvent: 'my-custom-input-element::input-event-name',
// This is a callback for the PersistentStateRegistry to manage changes from your element.
// The return value from this callback will be what is stored/loaded from memory
onChange: (customEvent) => {
return customEvent.detail.customValue
}
});
```
In this example, `` will initialize ``'s `customValue` property with data from the storage when it loads, and store the value returned from the `onChange` callback when the `my-custom-input-element::input-event-name` event fires on the element. _Note that this is only necessary if the custom element has a Shadow DOM._
Here is an exhaustive list of all the support input types
- `checkbox`
- `color`
- `date`
- `datetime-local`
- `email`
- `hidden`
- `month`
- `number`
- `password`
- `radio`
- `range`
- `search`
- `tel`
- `text`
- `time`
- `url`
- `week`
### ``
Note that with `radio` buttons the name has to be consistent between the elements:
```html
This
That
Or the Other
```
## Events
The `PersistentState::ElementInitialized` event is fired when `PersistentState` updates
the value of an element.
```js
document.addEventListener('PersistentState::ElementInitialized', (e) => {
const { elem } = e.detail;
// handle updated state
});
```
## Resetting Data
If you wish to remove the data stored in the browser for a specific `` form,
simply query for the web component and call the `reset()` method.
```js
let psForm = document.querySelector('persistent-state');
psForm.reset()
```
Additionally, if you wish to remove all data stored by this package, use the `PersistentStateRegistry`.
```js
// class is a singleton
new PersistentStateRegistry().resetAll();
```