use-chrome-storage
v1.3.2
Published
Custom React hooks for `chrome.storage.` You may use it for keeping global persisted state in chrome extensions.
Downloads
5,540
Maintainers
Readme
use-chrome-storage
☝️ This package is for usage in Chrome (and Chromium-based) Extensions, but it should work with Firefox extensions too.
Custom React hooks for chrome.storage.
You may use it to keep the global persisted state in Chrome Extensions.
Note: Since it's a React hook, it may be used only in the React context. So it's impossible to use this package in the background service worker.
- Simplify work with
chrome.storage
- Supports
chrome.storage.local
,chrome.storage.sync
, andchrome.storage.session
- Can be used as persisted state available in different extension's contexts (content script, popup, options page)
- Listen for
chrome.storage
changes and keep the local state updated
Install
npm i use-chrome-storage
Usage
This package requires the storage permission in manifest.json:
{
"name": "My Extension",
"permissions": [
"storage"
]
}
For usage with chrome.storage.local use useChromeStorageLocal
hook. For chrome.storage.sync
use useChromeStorageSync
hook. Use useChromeStorageSession
for chrome.storage.session
Usage of useChromeStorage
import React from 'react';
import {useChromeStorageLocal} from 'use-chrome-storage';
const LocalCounter = () => {
// If you need to state be preserved in `chrome.storage.sync` use useChromeStorageSync
// for `chrome.storage.session` use useChromeStorageSession
const [value, setValue, isPersistent, error, isInitialStateResolved] = useChromeStorageLocal('counterLocal', 0);
return (
<div>
<button
onClick={() => {
setValue(prev => (prev + 1));
}}
>
Increment in Local Storage
</button>
<div>Value: {value}</div>
<div>Persisted in chrome.storage.local: {isPersistent.toString()}</div>
<div>Error: {error}</div>
<div>Is state from chrome.storage already loaded? - {isInitialStateResolved.toString()}</div>
</div>
);
};
Usage of createChromeStorageStateHook
If you want to use the same key
in different components in different extension parts in the React context (like in PopUp,
content scripts,
) you need to use createChromeStorageStateHookLocal
(for chrome.storage.local),
createChromeStorageStateHookSync
(for chrome.storage.sync)
and createChromeStorageStateHookSession
(for chrome.storage.session).
Initialize storage:
// common/useSettingsStore.js
import {createChromeStorageStateHookLocal} from 'use-chrome-storage';
const SETTINGS_KEY = 'settings';
const INITIAL_VALUE = {
showAvatar: true,
showHistory: false,
};
export const useSettingsStore = createChromeStorageStateHookLocal(SETTINGS_KEY, INITIAL_VALUE);
Use useSettingsStore
on the options page:
// options.js
import React from 'react';
import {useSettingsStore} from './common/useSettingsStore';
const Options = () => {
const [settings, setSettings, isPersistent, error, isInitialStateResolved] = useSettingsStore();
const handleChange = event => {
setSettings(prevState => {
return {
...prevState,
[event.target.name]: event.target.checked
};
});
};
return (
<div>
<label>
<input
type="checkbox"
name="showAvatar"
checked={settings.showAvatar}
onChange={handleChange}
/>
<span>Show Avatar</span>
</label>
<label>
<input
type="checkbox"
name="showHistory"
checked={settings.showHistory}
onChange={handleChange}
/>
<span>Show History</span>
</label>
{isInitialStateResolved && <div>Initial state from "chrome.storage" is loaded</div>}
{!isPersistent && <div>Error writing to the chrome.storage: {error}</div>}
</div>
);
};
Or from the content script:
// contentScript.js
import React from 'react';
import Avatar from './common/Avatar';
import History from './common/History';
import {useSettingsStore} from './common/useSettingsStore';
const Card = () => {
const [settings] = useSettingsStore();
return (
<div>
{settings.showAvatar && <Avatar/>}
{settings.showHistory && <History/>}
</div>
);
};
In the same way, you may use it for PopUp.
Initial Value flow
Say we have the next hook:
const [value, setValue, isPersistent, error, isInitialStateResolved] = useChromeStorageLocal('counterLocal', 1);
Say in the chrome.storage.local
we already have: counterLocal: 10
.
Changes of value
:
value
is 1 (initialValue
set in the hook)useChromeStorageLocal
calls to Chrome API (this API is async) to get the value ofcounterLocal
.
value
changes to 10isInitialStateResolved
changes totrue
indicating thatvalue
synchronized with data saved inchrome.storage
Usage with chrome.storage.session
useChromeStorageSession
and createChromeStorageStateHookSessin
use chrome.storage.session
to persist state.
By default, it's not exposed to content scripts,
but this behavior can be changed by calling chrome.storage.session.setAccessLevel('TRUSTED_AND_UNTRUSTED_CONTEXTS')
(call it from the background script).
https://developer.chrome.com/docs/extensions/reference/storage/#method-StorageArea-setAccessLevel
Clearing or removing storage items
Suppose you want to reset all your stored items back to their initial values.
You could, for example, use chrome.storage.local.clear()
(or their 'session', 'sync' counterparts) to clear the entire storage.
Alternatively, you can use chrome.storage.local.remove(key)
to remove a specific storage item.
This will trigger a sync event in your useChromeStorage[Local|Session|Sync]
hooks, setting them back to their initial value.
API
useChromeStorageLocal(key, initialValue?)
The state will be persisted in chrome.storage.local
(and updated from chrome.storage.local
if it was updated in other
contexts). If you want to use this hook in more than one place, use createChromeStorageStateHookLocal
.
key: string
- The key used inchrome.storage.local
initialValue: any = undefined
- value which will be used ifchrome.storage.local
has no stored value yet or when a stored item is removed (unset)
Returns
[value, setValue, isPersistent, error, isInitialStateResolved]
value: any
- stateful value like first one returned fromReact.useState()
setValue: function
- function to updatevalue
like second one returned fromReact.useState()
isPersistent: boolean
- Will betrue
if data is persisted inchrome.storage.local
. In case of error duringchrome.storage.local.get
orchrome.storage.local.set
value will be stored in memory only andisPersistent
will be set tofalse
error: string
- IfisPersistent
istrue
will contain empty string. Otherwise, will contain error returned bychrome.runtime.lastError
.isInitialStateResolved: boolean
- will set totrue
onceinitialValue
will be replaced with stored in chrome.storage
useChromeStorageSync(key, initialValue?)
Similar to useChromeStorageLocal
but will use chrome.storage.sync
. State will be persisted
in chrome.storage.sync
(and updated from chrome.storage.sync
if it was updated in other contexts). If you want to
use this hook in more than one place, use createChromeStorageStateHookSync
.
key: string
- The key used inchrome.storage.sync
initialValue: any = undefined
- value which will be used ifchrome.storage.sync
has no stored value yet
Returns
[value, setValue, isPersistent, error]
value: any
- stateful value like the first one returned fromReact.useState()
setValue: function
- function to updatevalue
like the second one returned fromReact.useState()
isPersistent: boolean
- Will betrue
if data is persisted inchrome.storage.sync
. In case of an error duringchrome.storage.local.get
orchrome.storage.local.set
value will be stored in memory only andisPersistent
will be set tofalse
error: string
- IfisPersistent
istrue
will contain empty string. Otherwise, will contain error returned bychrome.runtime.lastError
.isInitialStateResolved: boolean
- will set totrue
onceinitialValue
will be replaced with stored in chrome.storage
useChromeStorageSession(key, initialValue?)
Similar to useChromeStorageLocal
but will use chrome.storage.session
. State will be persisted
in chrome.storage.session
(and updated from chrome.storage.session
if it was updated in other contexts). If you want
to use this hook in more than one place, use createChromeStorageStateHookSession
.
key: string
- The key used inchrome.storage.session
initialValue: any = undefined
- value which will be used ifchrome.storage.session
has no stored value yet
Returns
[value, setValue, isPersistent, error]
value: any
- stateful value like the first one returned fromReact.useState()
setValue: function
- function to updatevalue
like the second one returned fromReact.useState()
isPersistent: boolean
- Will betrue
if data is persisted inchrome.storage.session
. In case of an error duringchrome.storage.session.get
orchrome.storage.session.set
value will be stored in memory only andisPersistent
will be set tofalse
error: string
- IfisPersistent
istrue
will contain empty string. Otherwise, will contain an error returned bychrome.runtime.lastError
.isInitialStateResolved: boolean
- will set totrue
onceinitialValue
will be replaced with stored inchrome.storage.session
createChromeStorageStateHookLocal(key, initialValue?)
In case you want to use the same key
in different components/extension contexts you could create the state hook which can
be used across the extension. See example. The state will be persisted
in chrome.storage.local
.
key: string
- The key used inchrome.storage.local
initialValue: any = undefined
- value which will be used ifchrome.storage.local
has no stored value yet
Returns
function(): [any, (value: any) => void, boolean, string, boolean]
- useChromeStorageLocal
hook which may be used
across
extension's components/pages
createChromeStorageStateHookSync(key, initialValue?)
Similar to createChromeStorageStateHookLocal
but uses chrome.storage.sync
. In case you want to use the same key
in
different components/extension contexts you could create a state hook that can be used across the extension.
See example and replace with createChromeStorageStateHookSync
. State will be
persisted in chrome.storage.sync
.
key: string
- The key used inchrome.storage.sync
initialValue: any = undefined
- value which will be used ifchrome.storage.sync
has no stored value yet
Returns
function(): [any, (value: any) => void, boolean, string, boolean]
- useChromeStorageSync
hook which may be used
across extension's components/pages
createChromeStorageStateHookSession(key, initialValue?)
Similar to createChromeStorageStateHookLocal
but uses chrome.storage.session
. In case you want to use the same key
in
different components/extension contexts, you could create a state hook that can be used across extension.
See example and replace with createChromeStorageStateHookSession
. State will
be persisted in chrome.storage.session
.
key: string
- The key used inchrome.storage.session
initialValue: any = undefined
- value which will be used ifchrome.storage.session
has no stored value yet
Returns
function(): [any, (value: any) => void, boolean, string, boolean]
- useChromeStorageSession
hook which may be used
across extension's components/pages
Thanks to
use-local-storage-state for inspiration