Skip to main content

Statsig in React

Note since the @statsig/react-bindings works in conjuction with @statsig/js-client, the @statsig/js-client documentation can also be relevant for React implementations.

Installation​

Statsig uses a multi-package strategy, so you will need to install the Statsig client along with the @statsig/react-bindings.

npm install @statsig/js-client @statsig/react-bindings

Setup​

To use Statsig in React, you first must create an instance of the Statsig client and then pass it as a Prop to a StatsigProvider.

This will set your client as part of the StatsigContext and make it available to all Statsig hooks.

Synchronous Initialization (Cache)​

When callling StatsigClient.initalizeSync, the client will attempt to use cache values if they are available. The client will also fetch new values in the background and update the cache (not the current in-use values). In practice, unless an additional update call is made, this means that for the very first session of a given user, there will be no values, and not until the next session will the cache have values.

...

Asynchronous Initialization (Network)​

When calling StatsigClient.initializeAsync, the client will load values from cache and provide them to the client. The client will then fetch the latest values from the network, providing the ability to await the latest values from Statsig.

If you want the latest values, but do not want to await the asynchronous call, you may call initializeAsync and simply .catch the promise. Note that this could lead to values changing mid-session as newer values arrive from the network.

Note: To learn more about sync vs async initialization and how it can be customized, see Using EvaluationsDataAdapter

function Content() {
  const gate = useFeatureGate('a_gate');

  return <div>a_gate: {gate.value ? 'Passing' : 'Failing'}</div>;
}

function useAsyncClient(): { isLoading: boolean; client: StatsigClient } {
  const [isLoading, setIsLoading] = useState(true);

  const client = useMemo(() => {
    const instance = new StatsigClient(DEMO_CLIENT_KEY, { userID: 'a-user' });

    instance
      .initializeAsync()
      .then(() => {
        setIsLoading(false);
      })
      .catch((err) => {
        console.error(err);
      });

    return instance;
  }, []);

  return { client, isLoading };
}

export default function AsyncInitializeExample(): JSX.Element {
  const { client, isLoading } = useAsyncClient();

  if (isLoading) {
    return <div>Statsig Loading...</div>;
  }

  return (
    <StatsigProvider client={client}>
      <Content />
    </StatsigProvider>
  );
}

Hooks​

The react-bindings package exposes some hooks for convenience.

caution

When a hook is called, an exposure log is automatically triggered. If the check only happens conditionally, or later in a dialog, you will over expose your experiment!

We recommend using the useStatsigClient for these cases where you need the value conditionally, and then issuing the check inline later. Read on for more details.

FeatureGate Hooks​

There are three different ways to check a gate using hooks:

  • (recommended): useStatsigClient.checkGate is the safest way to check a gate, as it forces you to issue the check (and hence log the exposure) as close to the actual difference in experience as possible
  • useGateValue is a convience hook that returns the boolean value and is the most basic way to check if a gate is enabled.
  • useFeatureGate returns the FeatureGate object, if you need to check more information about the gate.

Note: useGateValue and useFeatureGate will log an exposure on render. useStatsigClient.checkGate will log an exposure when the function is called.

...

DynamicConfig Hooks​

  • (recommended): useStatsigClient.getDynamicConfig will trigger an exposure only when called
  • useDynamicConfig is a convience hook that returns the boolean value and is the most basic way to check if a gate is enabled.

Note: useDynamicConfig will log an exposure on render. useStatsigClient.getDynamicConfig will log an exposure when the function is called.

...

Experiment Hooks​

  • (recommended): useStatsigClient.getExperiment is the safest way to check an experiment, as it forces you to issue the check (and hence log the exposure) as close to the actual difference in experience as possible
  • useExperiment is a convience hook that returns the experiment and logs an exposure on render
...

Layer Hooks​

  • (recommended): useStatsigClient.getLayer in line with our other recommendations, but matters less for layers as exposures are triggered only when calling .get on a parameter
  • useLayer is a convience hook that returns the layer. This does not log an exposure
...

Log Event Hook​

Using the useStatsigClient hook, it is possible to get hold of the logEvent function.

...

StatsigUser Hook​

This hooks provides a way to get the current StatsigUser as well as providing methods for updating that user.

...