@cullenbond/use-local-storage-sync
v1.0.7
Published
React hook to save state to local storage and sync when updates are made to local storage
Downloads
11
Maintainers
Readme
useLocalStorageSync Hook (React)
To get started, simply run the following cmd to install the package:
npm install @cullenbond/use-local-storage-sync
Then import into the hook into your react component.
import { useLocalStorageSync } from "@cullenbond/use-local-storage-sync";
Example 1:
const [showButtons, setShowButtons] = useLocalStorageSync("showButtons", false);
Example 2:
const [persistedCount, setPersistedCount] = useLocalStorageSync("persistedCount", 0);
Example 3
const [userId, setUserId] = useLocalStorageSync("userId", "bob");
Example 4
const [groceryList, setGroceryList] = useLocalStorageSync("groceryList", ["Apples", "Oranges", "Bananas"]);
Advanced Loading and State sync usage
An abstract example of load logic using initialization value, to avoid infinite load loops. If you persist and load data to data stores bi-directionally.
const [showMenu, setShowMenu, showMenuError, showMenuInitialized] = useLocalStorageSync("showSettingsMenu", true)
useEffect(()=>{
if(showMenuInitialized){
// do things that might otherwise cause side effects
// update redux store to localStorage value, after initialization
}
},[showMenu])
useEffect(()=>{
if(showMenuInitialized){
// do things that might otherwise cause side effects
// update localStorage value, after initialization and when state is updated
setShowMenu(state.showMenu)
}
},[state.showMenu])
Parameters:
- Value Key Name
Similar to how JS Map() works we will identify the name of our value that is to be stored.
It is important to note that if you might to be persisting several variations of a name, to make sure the key name is unique.
Example:
const [buttonClickCount, setButtonClickCount] = useLocalStorageSync("buttonClickCount")
- Default Initial Value
The initial value takes precedence if no existing values have been stored locally.
Example:
const [buttonClickCount, setButtonClickCount] = useLocalStorageSync("buttonClickCount", 0)
- (Optional) getItem function
Method called when retrieving a stored value, before setting value to be used in state.
The hook will json.parse() the stored value, by default
Example:
const [buttonClickCount, setButtonClickCount] = useLocalStorageSync("buttonClickCount", 0, value => JSON.parse(value))
- (Optional) setItem function
Method called when setting a stored or synced value before setting the value.
The hook will json.stringify() the stored value, by default
Example:
const [buttonClickCount, setButtonClickCount] = useLocalStorageSync("buttonClickCount", 0, value => JSON.parse(value), value => JSON.stringify(value))
Avoid errors
- Overusing the hook with the same key can cause performance issues.
- Do not use with the same key in re-used components.
- unless you intentionally want to reference and update the same value
Common Usecases
- Storing website settings.
- Initializing Redux store on load.
- Persisting data for offline scenarios.
- Updating state across tabs and windows, in same browser
Anti-patterns:
- Avoid using in a compononent that is re-used often, and key points to the same value.
- Do not persist data that doesn't need to be stored long-term.
Return values
- value
- setValue
- error
- initialized