https://github.com/zoontek/react-atomic-state
Dead simple React global state management based on use-sync-external-store.
https://github.com/zoontek/react-atomic-state
Last synced: about 1 year ago
JSON representation
Dead simple React global state management based on use-sync-external-store.
- Host: GitHub
- URL: https://github.com/zoontek/react-atomic-state
- Owner: zoontek
- License: mit
- Created: 2020-07-28T16:56:22.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2025-01-28T13:46:57.000Z (over 1 year ago)
- Last Synced: 2025-03-30T15:11:28.015Z (about 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 1.58 MB
- Stars: 48
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ⚛️ react-atomic-state
Dead simple React global state management based on [`use-sync-external-store`](https://github.com/facebook/react/tree/master/packages/use-sync-external-store).
[](https://github.com/zoontek/react-atomic-state/blob/main/LICENSE)
[](https://www.npmjs.org/package/react-atomic-state)
[](https://bundlephobia.com/result?p=react-atomic-state)
## Installation
```bash
$ npm install --save react-atomic-state
# --- or ---
$ yarn add react-atomic-state
```
## ❓Motivation
I'm a **huge** fan of the _"state and props"_ couple, but sometimes I need to share a simple value to my entire application.
As I'm not a fan of the `Context` API and found existing global state management libraries overkill to me most of the times, I decided to publish this small library to cover this specific need 🙌.
## Usage
```tsx
// states/count.ts
import { atom, useAtom, useAtomWithSelector } from "react-atomic-state";
const count = atom(0);
export const decrement = () => count.set((prevCount) => prevCount - 1);
export const increment = () => count.set((prevCount) => prevCount + 1);
const unsubscribe = count.subscribe((value) => {
console.log(value); // log every update
});
// create a custom hook
export const useCount = () => useAtom(count);
// create a custom hook with selector
// (not to create a complex object store - it's often better to create multiple atoms, but to derive data)
export const useStringCount = () =>
useAtomWithSelector(count, (count) => count.toString());
```
```tsx
import { decrement, increment, useCount } from "./states/count.ts";
const Counter = () => {
const count = useCount();
return (
count: {count}
-1
+1
);
};
```
## API
### atom()
```ts
type atom = (initialValue: Value) => {
get: () => Value;
set: (value: Value | ((prevValue: Value) => Value)) => void;
subscribe: (callback: (value: Value) => void) => () => void;
reset: () => void;
};
```
### useAtom()
```ts
type useAtom = (
atom: Atom,
isEqual?: (prevValue: Value, nextValue: Value) => boolean,
) => Value;
```
### useAtomWithSelector()
```ts
type useAtomWithSelector = (
atom: Atom,
selector: (value: Value) => Selection,
isEqual?: (prevSelection: Selection, nextSelection: Selection) => boolean,
) => Value;
```