react-global-state-hooks v9.2.4

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 🎥
• 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:

const useContacts = createGlobalState(new Map(), {
  localStorage: {
    key: 'contacts',
  },
});

🛠 Creating a Global State

Define a global state in one line:

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

Now, use it inside a component:

const [count, setCount] = useCount();
return <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:

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

To access only the entities property:

const [contacts] = useContacts((state) => state.entities);
return (
  <ul>
    {contacts.map((contact) => (
      <li key={contact.id}>{contact.name}</li>
    ))}
  </ul>
);

📌 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:

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

Alternatively, you can pass dependencies inside an options object:

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

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

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

📌 Using Selectors in Components

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

✅ Selectors support inline selectors and dependencies

You can still use dependencies inside a selector hook:

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

✅ Selector hooks share the same state mutator

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

const [actions1] = useContactsArray();
const [actions2] = useContactsCount();

console.log(actions1 === actions2); // true

🎛 State Actions: Controlling State Modifications

Restrict state modifications by defining custom actions:

export const useContacts = createGlobalState(
  { filter: '', items: [] },
  {
    actions: {
      async fetch() {
        return async ({ setState }) => {
          const items = await fetchItems();
          setState({ items });
        };
      },
      setFilter(filter: string) {
        return ({ setState }) => {
          setState((state) => ({ ...state, filter }));
        };
      },
    },
  }
);

Now, instead of setState, the hook returns actions:

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

🌍 Accessing Global State Outside Components

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

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

✅ Subscribe to changes

const unsubscribe = contactsRetriever((state) => {
  console.log('State updated:', state);
});

✅ Subscriptions are great when one state depends on another.

const useSelectedContact = createGlobalState(null, {
  callbacks: {
    onInit: ({ setState, getState }) => {
      contactsRetriever(
        (state) => state.contacts,
        (contacts) => {
          if (!contacts.has(getState())) setState(null);
        }
      );
    },
  },
});

🎭 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

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

Wrap your app:

<CounterProvider>
  <MyComponent />
</CounterProvider>

Use the context state:

const [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

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

📌 Subscribing to an Observable

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

📌 Using Observables Inside Context

export const [useStateControls, useObservableBuilder] = useCounterContext.stateControls();
const createObservable = useObservableBuilder();
useEffect(() => {
  const unsubscribe = createObservable((count) => {
    console.log(`Updated count: ${count}`);
  });
  return unsubscribe;
}, []);

⚖️ createGlobalState vs. createContext

🔄 Lifecycle Methods

Global state hooks support lifecycle callbacks for additional control.

const useData = createGlobalState(
  { value: 1 },
  {
    callbacks: {
      onInit: ({ setState }) => {
        console.log('Store initialized');
      },
      onStateChanged: ({ state, previousState }) => {
        console.log('State changed:', previousState, '→', state);
      },
      computePreventStateChange: ({ state, previousState }) => {
        return state.value === previousState.value;
      },
    },
  }
);

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:

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

How to use it?

const [count, , metadata] = useCount();

metadata.renders += 1;

🎯 Ready to Try It?

📦 NPM Package: react-hooks-global-states

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