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 🎥

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

🗂️ Async Persist Storage

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

const useCount = createGlobalState(0, {
  asyncStorage: {
    key: "count",
  },
});

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

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

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

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

Using async persist storage

const useCount = createGlobalState(0, {
  asyncStorage: {
    key: "count",
  },
});

Inside your components

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