open-index/open-npm huggingface dataset:
npm package: @nicnocquee/use-local-storage-hook
Description: A custom hook that simplifies storing, retrieving, and clearing any types of data from the local storage including sync with other tabs
Latest version: 0.0.5

# useLocalStorage React Hook

A type-safe, composable React hook for synchronizing state with `localStorage`, supporting any serializable value, with cross-tab updates and legacy data migration. Powered by [superjson](https://github.com/blitz-js/superjson) for robust serialization.

## Features

- **Type-safe**: Works with any serializable value (string, number, object, array, boolean, Date, null, undefined)
- **Cross-tab sync**: Updates state across browser tabs/windows
- **Legacy migration**: Migrates old values to a new, safer format
- **Clear API**: Get, set, and clear values with a simple tuple

## Installation

```
npm install @nicnocquee/use-local-storage-hook superjson
```

> **Peer dependencies:**
>
> - `react` >= 18.3.1
> - `superjson` >= 2.2.2

## Usage

```tsx
import { useLocalStorage } from "@nicnocquee/use-local-storage-hook";

const [value, setValue, clearValue] = useLocalStorage<string>(
  "my-key",
  "default"
);
```

### Example: Storing String

```tsx
const [name, setName] = useLocalStorage<string>("name", "Alice");
```

### Example: Storing Object

```tsx
const [user, setUser] = useLocalStorage<{ id: number; name: string }>("user", {
  id: 1,
  name: "Alice"
});
```

### Example: Storing Array

```tsx
const [items, setItems] = useLocalStorage<number[]>("items", [1, 2, 3]);
```

### Example: Storing Boolean

```tsx
const [flag, setFlag] = useLocalStorage<boolean>("flag", false);
```

### Example: Clearing a value

```tsx
const [value, setValue, clearValue] = useLocalStorage("key", "default");
clearValue(); // value becomes undefined
```

By default, the value is not actually deleted from localStorage, it just sets it to "cleared" type. In this case, the "data" variable will return undefined.

If you want to actually delete the value from localStorage, you can call the `clearValue` function with `purge` set to `true`.

```tsx
const [value, setValue, clearValue] = useLocalStorage("key", "default");
clearValue(true); // value becomes "default" because it's the initial value
```

## API

```ts
const [value, setValue, clearValue] = useLocalStorage<T>(key: string, initialValue?: T);
```

- `value`: The current value from localStorage (or `initialValue` if the key is not found in localStorage)
- `setValue(value: T)`: Sets the value in localStorage
- `clearValue(purge?: boolean)`: Clears the value. When `purge` is true, the value is actually deleted from localStorage and the `value` variable will return the `initialValue` parameter. Otherwise, it just sets it to "cleared" type and the `value` variable will return undefined.

## Testing

This project uses [Vitest](https://vitest.dev/) and [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) for tests. To run tests:

```
npm test
```

## License

MIT