# @cullenbond/use-local-storage-sync

> React hook to save state to local storage and sync when updates are made to local storage

Latest version **1.0.7** (published 2024-03-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cullenbond/use-local-storage-sync
pnpm add @cullenbond/use-local-storage-sync
yarn add @cullenbond/use-local-storage-sync
bun add @cullenbond/use-local-storage-sync
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2024-03-01 |
| First published | 2024-03-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 6.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Cullen Bond |
| Maintainers | cullenbond |
| Keywords | react, localstorage, persist, data, sync, data, pub, sub |

## Links

- npm: https://www.npmjs.com/package/@cullenbond/use-local-storage-sync
- Repository: https://github.com/StaticSpark/use-local-storage-sync
- Homepage: https://github.com/StaticSpark/use-local-storage-sync#readme
- Issues: https://github.com/StaticSpark/use-local-storage-sync/issues
- npm.io page: https://npm.io/package/@cullenbond/use-local-storage-sync

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.0.7 (latest) — 2024-03-01
- 1.0.6 — 2024-03-01
- 1.0.5 — 2024-03-01
- 1.0.4 — 2024-03-01
- 1.0.3 — 2024-03-01
- 1.0.2 — 2024-03-01
- 1.0.1 — 2024-03-01
- 1.0.0 — 2024-03-01

## 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:

1. 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")

2. Default Initial Value

The initial value takes precedence if no existing values have been stored locally.

Example:

    const [buttonClickCount, setButtonClickCount] = useLocalStorageSync("buttonClickCount", 0)

3. (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))

4. (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

1. value
2. setValue
3. error
4. initialized

---
_Source: https://npm.io/package/@cullenbond/use-local-storage-sync · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._