react-global-state-hooks 🌟

Effortless global state management for React & React Native and Preact! 🚀 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 🎥

Works seamlessly with React & React Native:

• 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.

🗂️ Persisting State with LocalStorage

To persist the global state using LocalStorage, simply add the localStorage option:

1const useContacts = createGlobalState(new Map(), {
2  localStorage: {
3    key: 'contacts',
4  },
5});

🛠 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! 🚀