https://github.com/phantomstudios/use-local-state
A simple React hook that allows you to store data within LocalStorage with the same interface as the standard React.useState hook.
https://github.com/phantomstudios/use-local-state
hook localstorage react state
Last synced: 4 months ago
JSON representation
A simple React hook that allows you to store data within LocalStorage with the same interface as the standard React.useState hook.
- Host: GitHub
- URL: https://github.com/phantomstudios/use-local-state
- Owner: phantomstudios
- License: mit
- Created: 2021-02-28T11:27:55.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-10-01T16:04:01.000Z (5 months ago)
- Last Synced: 2025-10-03T12:07:44.964Z (4 months ago)
- Topics: hook, localstorage, react, state
- Language: TypeScript
- Homepage:
- Size: 1.6 MB
- Stars: 2
- Watchers: 6
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Support: SUPPORT.md
Awesome Lists containing this project
README
# use-local-state
[![NPM version][npm-image]][npm-url]
[![Actions Status][ci-image]][ci-url]
[![PR Welcome][npm-downloads-image]][npm-downloads-url]
A simple React hook that allows you to store data within `LocalStorage` with the same interface as the standard `React.useState` hook.
## Introduction
Just swap out your `useState` calls with `useLocalState` to persist the data between refreshes. This hook is also SSR safe and does not break when used without `window` existing.
```javascript
import useLocalState from "@phntms/use-local-state";
const [value, setValue, resetValue] = useLocalState("KEY", "");
```
## Installation
Install this package with `npm`.
```bash
npm i @phntms/use-local-state
```
## Usage
Store a boolean to track if a user has accepted terms of use.
```JSX
import React from 'react';
import useLocalState from '@phntms/use-local-state';
const TermsExample = () = {
const [accepted, setAccepted] = useLocalState("TERMS_ACCEPTED", false);
return (
<>
Welcome
{!accepted && <>
Do you accept our terms?
setAccepted(true)}>Accept
>}
>
);
}
```
Store a list of bookmarks.
```JSX
import React from 'react';
import useLocalState from '@phntms/use-local-state';
interface Bookmark {
title: string;
url: string;
}
const BookmarkExample = () = {
const [bookmarks, setBookmarks, clearBookmarks] = useLocalState("BOOKMARKS", []);
const addBookmark = (bookmark: Bookmark) => setBookmarks([...bookmarks, bookmark]);
return (
<>
Bookmarks
Clear Bookmarks
{bookmarks.map(((bookmark, i) => (
-
{bookmark.title}
)))}
>
);
}
```
## API
### Input
- `key` : Required - The key of type `string` to store within `LocalStorage`.
- `initialValue` : Required - The default/initial value of type `T` if the key is not found within the `LocalStorage` object.
### Output
An array containing the value, a function to set the value and another function to reset the value.
- `[0]` : The value of the data stored in LocalStorage or the defaultValue if not set.
- `[1]` : A function to set the value stored in LocalStorage. Signature is exactly like the standard [React.useState](https://reactjs.org/docs/hooks-state.html) hook.
- `[2]` : A function to reset the data stored in the LocalStorage.
[npm-image]: https://img.shields.io/npm/v/@phntms/use-local-state.svg?style=flat-square&logo=react
[npm-url]: https://npmjs.org/package/@phntms/use-local-state
[npm-downloads-image]: https://img.shields.io/npm/dm/@phntms/use-local-state.svg
[npm-downloads-url]: https://npmcharts.com/compare/@phntms/use-local-state?minimal=true
[ci-image]: https://github.com/phantomstudios/use-local-state/workflows/test/badge.svg
[ci-url]: https://github.com/phantomstudios/use-local-state/actions