react-native-global-state-hooks 🌟

Effortless global state management for React & React Native! 🚀 Define a global state in just one line of code and enjoy lightweight, flexible, and scalable state management. Try it now on CodePen and see it in action! ✨

---

🔗 Explore More

• Live Example 📘
• Video Overview 🎥
• react-hooks-global-states compatible with both React & React Native
• react-global-state-hooks specific for web applications (local-storage integration).
• react-native-global-state-hooks specific for React Native projects (async-storage integration).

---

🚀 React Hooks Global States - DevTools Extension

React Hooks Global States includes a dedicated, devTools extension to streamline your development workflow! Easily visualize, inspect, debug, and modify your application's global state in real-time right within your browser.

🔗 Install the DevTools Extension for Chrome

📸 DevTools Highlights

Track State Changes	Modify the State
Effortlessly monitor state updates and history.	Instantly edit global states directly from the extension.

---

Restore the State	Custom Actions Granularity
Quickly revert your application to a previous state.	Precisely debug specific actions affecting state changes.

🗂️ Async Persist Storage

To persist the global state using Async Storage, simply add the asyncStorage option:

1const useCount = createGlobalState(0, {
2  asyncStorage: {
3    key: "count",
4  },
5});

🔹 How It Works

✅ Automatically syncs the state with Async Storage if the value is serializable. ✅ Provides an isAsyncStorageReady flag to indicate when the async storage has been reviewed and committed. ✅ Uses @react-native-async-storage/async-storage by default (make sure to install this package if needed). ✅ Allows custom async storage managers with asyncStorageWrapper.addAsyncStorageManager(customAsyncStorageManager);

Inside your components:

1const [count, setCount, { isAsyncStorageReady }] = useCount();

If you specify a key in asyncStorage, the state value persists automatically when serializable. When connecting to async storage, expect a second render that updates isAsyncStorageReady, indicating that the storage has been reviewed and the state is committed.

🔧 Custom Async Storage Manager

You can configure your own storage selection by using asyncStorageWrapper.addAsyncStorageManager. Ensure that the manager is added before any hook is called.

index.ts

1import { asyncStorageWrapper } from "react-global-state-hooks";
2asyncStorageWrapper.addAsyncStorageManager(customAsyncStorageManager);

🛠 Creating a Global State

Define a global state in one line:

1import { createGlobalState } from "react-hooks-global-states/createGlobalState";
2export const useCount = createGlobalState(0);

Now, use it inside a component:

1const [count, setCount] = useCount();
2return <Button onClick={() => setCount((count) => count + 1)}>{count}</Button>;

Works just like useState, but the state is shared globally! 🎉

---

🎯 Selectors: Subscribing to Specific State Changes

For complex state objects, you can subscribe to specific properties instead of the entire state:

1export const useContacts = createGlobalState({ entities: [], selected: new Set<number>() });

To access only the entities property:

1const [contacts] = useContacts((state) => state.entities);
2return (
3  <ul>
4    {contacts.map((contact) => (
5      <li key={contact.id}>{contact.name}</li>
6    ))}
7  </ul>
8);

📌 Using Dependencies in Selectors

You can also add dependencies to a selector. This is useful when you want to derive state based on another piece of state (e.g., a filtered list). For example, if you're filtering contacts based on a filter value:

1const [contacts] = useContacts(
2  (state) => state.entities.filter((item) => item.name.includes(filter)),
3  [filter]
4);

Alternatively, you can pass dependencies inside an options object:

1const [contacts] = useContacts((state) => state.entities.filter((item) => item.name.includes(filter)), {
2  dependencies: [filter],
3  isEqualRoot: (a, b) => a.entities === b.entities,
4});

Unlike Redux, where only root state changes trigger re-selection, this approach ensures that derived values recompute when dependencies change while maintaining performance.

---

🔄 Reusing Selectors

📌 Creating a Selector

1export const useContactsArray = useContacts.createSelectorHook((state) => state.entities);
2export const useContactsCount = useContactsArray.createSelectorHook((entities) => entities.length);

📌 Using Selectors in Components

1const [contacts] = useContactsArray();
2const [count] = useContactsCount();

✅ Selectors support inline selectors and dependencies

You can still use dependencies inside a selector hook:

1const [filteredContacts] = useContactsArray(
2  (contacts) => contacts.filter((c) => c.name.includes(filter)),
3  [filter]
4);

✅ Selector hooks share the same state mutator

The stateMutator remains the same across all derived selectors, meaning actions and setState functions stay consistent.

1const [actions1] = useContactsArray();
2const [actions2] = useContactsCount();
3
4console.log(actions1 === actions2); // true

---

🎛 State Actions: Controlling State Modifications

Restrict state modifications by defining custom actions:

1export const useContacts = createGlobalState(
2  { filter: "", items: [] },
3  {
4    actions: {
5      async fetch() {
6        return async ({ setState }) => {
7          const items = await fetchItems();
8          setState({ items });
9        };
10      },
11      setFilter(filter: string) {
12        return ({ setState }) => {
13          setState((state) => ({ ...state, filter }));
14        };
15      },
16    },
17  }
18);

Now, instead of setState, the hook returns actions:

1const [filter, { setFilter }] = useContacts();

---

🌍 Accessing Global State Outside Components

Use stateControls() to retrieve or update state outside React components:

1const [contactsRetriever, contactsApi] = useContacts.stateControls();
2console.log(contactsRetriever()); // Retrieves the current state

✅ Subscribe to changes

1const unsubscribe = contactsRetriever((state) => {
2  console.log("State updated:", state);
3});

✅ Subscriptions are great when one state depends on another.

1const useSelectedContact = createGlobalState(null, {
2  callbacks: {
3    onInit: ({ setState, getState }) => {
4      contactsRetriever(
5        (state) => state.contacts,
6        (contacts) => {
7          if (!contacts.has(getState())) setState(null);
8        }
9      );
10    },
11  },
12});

---

🎭 Using Context for Scoped State

• Scoped State – Context state is isolated inside the provider.
• Same API – Context supports selectors, actions, and state controls.

📌 Creating a Context

1import { createContext } from "react-global-state-hooks/createContext";
2export const [useCounterContext, CounterProvider] = createContext(0);

Wrap your app:

1<CounterProvider>
2  <MyComponent />
3</CounterProvider>

Use the context state:

1const [count] = useCounterContext();

📌 Context Selectors

Works just like global state, but within the provider.

---

🔥 Observables: Watching State Changes

Observables let you react to state changes via subscriptions.

📌 Creating an Observable

1export const useCounter = createGlobalState(0);
2export const counterLogs = useCounter.createObservable((count) => `Counter is at ${count}`);

📌 Subscribing to an Observable

1const unsubscribe = counterLogs((message) => {
2  console.log(message);
3});

📌 Using Observables Inside Context

1export const [useStateControls, useObservableBuilder] = useCounterContext.stateControls();
2const createObservable = useObservableBuilder();
3useEffect(() => {
4  const unsubscribe = createObservable((count) => {
5    console.log(`Updated count: ${count}`);
6  });
7  return unsubscribe;
8}, []);

---

⚖️ createGlobalState vs. createContext

Feature	createGlobalState	createContext
Scope	Available globally across the entire app	Scoped to the Provider where it’s used
How to Use	const useCount = createGlobalState(0)	const [useCountContext, Provider] = createContext(0)
createSelectorHook	useCount.createSelectorHook	useCountContext.createSelectorHook
inline selectors?	✅ Supported	✅ Supported
Custom Actions	✅ Supported	✅ Supported
Observables	useCount.createObservable	const [, useObservableBuilder] = useCountContext.stateControls()
State Controls	useCount.stateControls()	const [useStateControls] = useCountContext.stateControls()
Best For	Global app state (auth, settings, cache)	Scoped module state, reusable component state, or state shared between child components without being fully global

🔄 Lifecycle Methods

Global state hooks support lifecycle callbacks for additional control.

1const useData = createGlobalState(
2  { value: 1 },
3  {
4    callbacks: {
5      onInit: ({ setState }) => {
6        console.log("Store initialized");
7      },
8      onStateChanged: ({ state, previousState }) => {
9        console.log("State changed:", previousState, "→", state);
10      },
11      computePreventStateChange: ({ state, previousState }) => {
12        return state.value === previousState.value;
13      },
14    },
15  }
16);

Use onInit for setup, onStateChanged to listen to updates, and computePreventStateChange to prevent unnecessary updates.

Metadata

There is a possibility to add non reactive information in the global state:

1const useCount = createGlobalState(0, { metadata: { renders: 0 } });

How to use it?

1const [count, , metadata] = useCount();
2
3metadata.renders += 1;

🎯 Ready to Try It?

📦 NPM Package: react-hooks-global-states

🚀 Simplify your global state management in React & React Native today! 🚀

Using async persist storage

1const useCount = createGlobalState(0, {
2  asyncStorage: {
3    key: "count",
4  },
5});

Inside your components

1const [count, setCount, { isAsyncStorageReady }] = useCount();

• if you specify a key into the asyncStorage this will persist the state value if the same is serializable
• when connecting to the async storage you can expect a second render which will update isAsyncStorageReady indicating that the async storage was already reviewed and the state value is committed.

The async storage default functionality depends on @react-native-async-storage/async-storage but this dependency is optional, install the package as a dependency if you want to enable persisted state.

optionally you can configure your own selection for persisting storage by using asyncStorageWrapper.addAsyncStorageManager, notice that the manager should be added before any hook gets call;