Global state API

Reference for createGlobalState, its options, lifecycle callbacks and the members of the hook.

API referenceTypeScriptTry an example

createGlobalState

createGlobalState(initialState, options?) => hook

initialState is a value or a function returning one. Without options, the hook’s second tuple item is a setState function. With actions, it is the actions object.

Options

Option	Type	Purpose
`name`	`string`	Name shown in DevTools and used for debugging.
`metadata`	value or function	Non-reactive side data. Available as the tuple’s third item and as `store.metadata`.
`actions`	`Record<string, (...args) => (tools) => any>`	Named state changes. See Actions.
`callbacks`	object	Lifecycle hooks, below.
`localStorage`	object	Persistence (web package). See Persistence.

Callbacks

callbacks.ts

import { createGlobalState } from 'react-global-state-hooks';

export const log: string[] = [];

export const useGuarded = createGlobalState(
  { count: 0 },
  {
    name: 'guarded-counter',
    metadata: { changes: 0 },
    callbacks: {
      // Runs when the store is created. May return a cleanup function.
      onInit: ({ getState }) => {
        log.push(`init:${getState().count}`);

        return () => log.push('cleanup');
      },

      // Runs after each accepted state change.
      onStateChanged: ({ previousState, state, setMetadata }) => {
        log.push(`changed:${previousState.count}->${state.count}`);
        setMetadata((metadata: { changes: number }) => ({ changes: metadata.changes + 1 }));
      },

      // Return true to reject a change before it is applied.
      computePreventStateChange: ({ state }) => state.count < 0,
    },
  },
);

Callback	When it runs
`onInit(tools)`	When the store is created and again after `reset()`. Return a cleanup function to run before the next `reset()` or `dispose()`.
`onStateChanged({ previousState, state, ...tools })`	After a state change is applied.
`onSubscribed(tools, subscription)`	Each time a subscription is added.
`computePreventStateChange({ previousState, state, ...tools })`	Before a change is applied. Return `true` to reject it.
`onUnMount(store)`	When a context provider unmounts. Only applies to contexts.

The hook

useStore(selector?, depsOrOptions?) returns [selected, setStateOrActions, metadata].

Option	Purpose
`dependencies`	Values the selector reads from outside the store.
`isEqual(current, next)`	Compare the selected value. Default `===`.
`isEqualRoot(current, next)`	Compare the whole state. Default `===`.

Store members

Member	Signature	Notes
`getState`	`() => State`
`setState`	`(valueOrUpdater, { forceUpdate?, identifier? }?) => void`	`forceUpdate` notifies even when the reference is unchanged. `identifier` labels the change in DevTools.
`subscribe`	`(callback)` or `(selector, callback, options?)`	`options`: `skipFirst`, `isEqual`, `isEqualRoot`. Returns an unsubscribe function.
`select`	`(selector, depsOrOptions?) => Selected`	Hook that returns only the selection.
`createSelectorHook`	`(selector, { isEqual?, isEqualRoot?, name? }?) => hook`	Read-only shared hook that returns the value. Chains.
`createObservable`	`(selector, { isEqual?, isEqualRoot?, name? }?) => observable`	Subscribable and chainable.
`metadata`	`Metadata` (getter)
`getMetadata` / `setMetadata`	`() => Metadata` / `(valueOrUpdater) => void`	`getMetadata` is deprecated in favour of `metadata`.
`reset`	`() => void` or `(state, metadata) => void`	A test helper: restores the initial state and re-runs `onInit`. Function initializers are re-evaluated.
`dispose`	`() => void`	Removes subscriptions and runs cleanup.
`actions`	object or `null`	The actions object.
`use`	hook	The same function as the hook.