React Client SDK

Source code: statsig-io/js-client-monorepo

Set Up the SDK

Install the SDK

If you need a starter project, follow the official React quickstart. Looking for Next.js instead? See the Next.js SDK docs.

AI-powered Setup

Setup Statsig in 90 seconds by copying this AI prompt into your IDE:

You are a frontend engineer integrating the Statsig SDK into a React app. Follow these instructions carefully:
1. Install the required Statsig packages:
     npm install @statsig/react-bindings @statsig/session-replay @statsig/web-analytics

2. In the main component file (`App.jsx` or `App.tsx`):
   - Import `StatsigProvider` and `useClientAsyncInit` from `@statsig/react-bindings`
   - Import `StatsigAutoCapturePlugin` from `@statsig/web-analytics` and `StatsigSessionReplayPlugin` from `@statsig/session-replay`
   - Initialize the SDK using your client key: 'YOUR-CLIENT-API-KEY'
   - Use `userID` from an existing variable if it's already declared in the file; otherwise, default to `'a-user'`
   - Wrap the existing app content inside `<StatsigProvider>`, using `<div>Loading...</div>` as the `loadingComponent`

3. DO NOT remove any existing JSX content from the component. Just wrap it.

4. Here is what the final file structure should look like:

    import { StatsigProvider, useClientAsyncInit } from '@statsig/react-bindings';
    import { StatsigAutoCapturePlugin } from '@statsig/web-analytics';
    import { StatsigSessionReplayPlugin } from '@statsig/session-replay';
    import YourApp from './YourApp';

    function App() {
      const id = typeof userID !== 'undefined' ? userID : 'a-user';
      const { client } = useClientAsyncInit(
        'YOUR-CLIENT-API-KEY',
        { userID: id },
        { plugins: [new StatsigAutoCapturePlugin(), new StatsigSessionReplayPlugin()] }
      );

      return (
        <StatsigProvider client={client} loadingComponent={<div>Loading...</div>}>
          <YourApp />
        </StatsigProvider>
      );
    }

5. Ask the user to provide their CLIENT-API-KEY and insert it where prompted above.

Install Packages

npm
yarn

npm install @statsig/react-bindings

yarn add @statsig/react-bindings

Add @statsig/session-replay and @statsig/web-analytics if you plan to enable Session Replay or Auto Capture.

Initialize the SDK

Next, initialize the SDK with a client SDK key from the “API Keys” tab on the Statsig console. These keys are safe to embed in a client application.Along with the key, pass in a User Object with the attributes you’d like to target later on in a gate or experiment.

Wrap Your App With `StatsigProvider`

Provide your client SDK key and initial user when you render the provider.

import { StatsigProvider } from '@statsig/react-bindings';

function App() {
  return (
    <StatsigProvider sdkKey="client-KEY" user={{ userID: '1234', email: 'example@statsig.com' }}>
      <div>Hello world</div>
    </StatsigProvider>
  );
}

Typical Project Structure

Most projects render a root component inside the provider.

// App.tsx
import RootPage from './RootPage';
import { StatsigProvider } from '@statsig/react-bindings';

export default function App() {
  return (
    <StatsigProvider sdkKey="client-KEY" user={{ userID: '1234' }}>
      <RootPage />
    </StatsigProvider>
  );
}

// RootPage.tsx
export default function RootPage() {
  return <div>Hello World</div>;
}

Need to balance startup speed with freshness? Review Initialization Strategies for bootstrap and async options.

Use the SDK

Use useStatsigClient inside components to retrieve the client when you need to evaluate something.

import { useStatsigClient } from '@statsig/react-bindings';

const { client } = useStatsigClient();

Checking a Feature Flag/Gate

Now that your SDK is initialized, let’s check a Feature Gate. Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always CLOSED or OFF (think return false;) by default.

import {
  useFeatureGate,
  useGateValue,
  useStatsigClient,
} from '@statsig/react-bindings';

const { checkGate } = useStatsigClient();
const gateValue = useGateValue('my_gate');
const gate = useFeatureGate('my_gate');

return (
  <div>
    {checkGate('my_gate') && <p>Passing</p>}
    {gateValue && <p>Passing</p>}
    {gate.value && <p>Passing ({gate.details.reason})</p>}
  </div>
);

Reading a Dynamic Config

Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, Dynamic Configs can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:

import { useDynamicConfig, useStatsigClient } from '@statsig/react-bindings';

const config = useDynamicConfig('my_dynamic_config');
const { getDynamicConfig } = useStatsigClient();

return (
  <div>
    <p>Reason: {config.details.reason}</p>
    <p>Value: {config.get('a_value', 'fallback_value')}</p>
    <p>Another Value: {getDynamicConfig('my_dynamic_config').get('a_bool', false)}</p>
  </div>
);

Getting a Layer/Experiment

Then we have Layers/Experiments, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of layers to enable quicker iterations with parameter reuse.

import { useExperiment, useStatsigClient } from '@statsig/react-bindings';

const experiment = useExperiment('my_experiment');
const { getExperiment } = useStatsigClient();

return (
  <div>
    <p>Group: {getExperiment('my_experiment').groupName}</p>
    <p>Value: {experiment.get('a_value', 'fallback_value')}</p>
  </div>
);

import { useLayer, useStatsigClient } from '@statsig/react-bindings';

const layer = useLayer('my_layer');
const { getLayer } = useStatsigClient();

return (
  <div>
    <p>Group: {getLayer('my_layer').groupName}</p>
    <p>Value: {layer.get('a_value', 'fallback_value')}</p>
  </div>
);

Logging an Event

Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:

import { useStatsigClient } from '@statsig/react-bindings';

const { logEvent } = useStatsigClient();

return <button onClick={() => logEvent('my_event')}>Click Me</button>;

Parameter Stores

Parameter Stores hold a set of parameters for your mobile app. These parameters can be remapped on-the-fly from a static value to a Statsig entity (Feature Gates, Experiments, and Layers), so you can decouple your code from the configuration in Statsig. Read more about Param Stores here.

Manage Users

Updating User Properties

Switch identities when a user logs in or when you collect richer attributes.

import { useGateValue, useStatsigUser } from '@statsig/react-bindings';

export default function AccountBanner() {
  const gateValue = useGateValue('check_user');
  const { updateUserAsync } = useStatsigUser();

  return (
    <div>
      <div>Gate is {gateValue ? 'passing' : 'failing'}.</div>
      <button onClick={() => updateUserAsync({ userID: '2' })}>Login</button>
    </div>
  );
}

Loading State

Wait for the latest values during initialization with either the provider or the async hook.

StatsigProvider
useClientAsyncInit

import { StatsigProvider } from '@statsig/react-bindings';

export function App() {
  return (
    <StatsigProvider
      sdkKey="client-KEY"
      user={{ userID: 'a-user' }}
      loadingComponent={<div>Loading...</div>}
    >
      <YourComponent />
    </StatsigProvider>
  );
}

import { StatsigProvider, useClientAsyncInit } from '@statsig/react-bindings';

export function App() {
  const { client, isLoading } = useClientAsyncInit(
    'client-KEY',
    { userID: 'a-user' },
  );

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

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

React Hooks

Hooks that read gates, configs, experiments, or layers will log exposures on render. Use useStatsigClient to defer checks until you actually change the UI.

Feature Gate Hooks

Recommended: useStatsigClient().checkGate logs when invoked.
useGateValue returns the boolean value and logs immediately.
useFeatureGate returns the full gate object with details.

import {
  useFeatureGate,
  useGateValue,
  useStatsigClient,
} from '@statsig/react-bindings';

const { checkGate } = useStatsigClient();
const gateValue = useGateValue('my_gate');
const gate = useFeatureGate('my_gate');

return (
  <div>
    {checkGate('my_gate') && <p>Passing</p>}
    {gateValue && <p>Passing</p>}
    {gate.value && <p>Passing ({gate.details.reason})</p>}
  </div>
);

Dynamic Config Hooks

Recommended: useStatsigClient().getDynamicConfig defers exposure until called.
useDynamicConfig logs on render.

import { useDynamicConfig, useStatsigClient } from '@statsig/react-bindings';

const config = useDynamicConfig('my_dynamic_config');
const { getDynamicConfig } = useStatsigClient();

return (
  <div>
    <p>Reason: {config.details.reason}</p>
    <p>Value: {config.get('a_value', 'fallback_value')}</p>
    <p>Another Value: {getDynamicConfig('my_dynamic_config').get('a_bool', false)}</p>
  </div>
);

Experiment Hooks

Recommended: useStatsigClient().getExperiment to control exposures.
useExperiment logs on render.

import { useExperiment, useStatsigClient } from '@statsig/react-bindings';

const experiment = useExperiment('my_experiment');
const { getExperiment } = useStatsigClient();

return (
  <div>
    <p>Group: {getExperiment('my_experiment').groupName}</p>
    <p>Value: {experiment.get('a_value', 'fallback_value')}</p>
  </div>
);

Layer Hooks

Layers only log exposures when you call .get().

import { useLayer, useStatsigClient } from '@statsig/react-bindings';

const layer = useLayer('my_layer');
const { getLayer } = useStatsigClient();

return (
  <div>
    <p>Group: {getLayer('my_layer').groupName}</p>
    <p>Value: {layer.get('a_value', 'fallback_value')}</p>
  </div>
);

Parameter Store Hooks

import { useParameterStore } from '@statsig/react-bindings';

function MyComponent() {
  const store = useParameterStore('my_parameter_store');
  const title = store.get('page_title', 'Default Title');
  const maxItems = store.get('max_items', 10);
  const isEnabled = store.get('feature_enabled', false);

  const storeNoExposure = useParameterStore('my_parameter_store', {
    disableExposureLog: true,
  });

  return <div>{title}</div>;
}

Log Events From Hooks

import { useStatsigClient } from '@statsig/react-bindings';

const { logEvent } = useStatsigClient();

return <button onClick={() => logEvent('my_event')}>Click Me</button>;

StatsigUser Hook

import { useStatsigUser } from '@statsig/react-bindings';

const { user, updateUserSync } = useStatsigUser();

return (
  <div>
    <p>Current User: {user.userID}</p>
    <button onClick={() => updateUserSync({ userID: 'some-other-user' })}>
      Update User
    </button>
  </div>
);

Direct Access to the Client

import { useStatsigClient } from '@statsig/react-bindings';

const { client } = useStatsigClient();
console.log('stableID', client.getContext().stableID);

Client Initialization Hooks

useClientAsyncInit — fetches the latest values before rendering.
useClientBootstrapInit — bootstrap from server-provided values.

You can also initialize your own client instance manually. See Initialization Strategies for alternatives.

Statsig Options

LoggingEnabledOption

default:"browser-only"

Controls logging behavior.

browser-only (default): log events from browser environments.
disabled: never send events.
always: log in every environment, including non-browser contexts.

boolean

deprecated

Use loggingEnabled: 'disabled' instead.

boolean

default:"false"

Skip generating a device-level Stable ID.

boolean

default:"false"

Recompute every evaluation instead of using the memoized result.

string

Override the generated session ID.

boolean

default:"false"

Persist Stable ID in cookies for cross-domain tracking.

boolean

Prevent any local storage writes (disables caching).

NetworkConfig

Override network endpoints per request type.

StatsigEnvironment

Set environment-wide defaults (for example { tier: 'staging' }).

LogLevel

default:"Warn"

Console verbosity.

number

default:"50"

Max events per log batch.

number

default:"10_000"

Interval between automatic flushes.

OverrideAdapter

Modify evaluations before returning them.

boolean

default:"true"

Attach the current page URL to logged events.

boolean

default:"false"

Send requests without Statsig-specific encoding.

LogEventCompressionMode

default:"Enabled"

Control compression for batched events.

boolean

deprecated

Use logEventCompressionMode instead.

EvaluationsDataAdapter

Provide a custom data adapter to control caching/fetching.

CustomCacheKeyGenerator

Override cache key generation for stored evaluations.

Network Config Options

string

default:"https://api.statsig.com"

Base URL for all requests (append /v1).

string

default:"https://prodregistryv2.org/v1/rgstr"

Endpoint for event uploads.

string[]

Fallback endpoints for event uploads.

number

default:"10000"

Request timeout in milliseconds.

boolean

Disable all outbound requests; combine with loggingEnabled: 'disabled' to silence log warnings.

function

Provide custom transport (e.g., Axios).

string

default:"https://featureassets.org/v1/initialize"

Endpoint for initialization requests.

Testing

Mock Statsig hooks in Jest to isolate component logic.

import { StatsigProvider, useFeatureGate, useExperiment } from '@statsig/react-bindings';

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

  return (
    <div>
      <div data-testid="gate_test">a_gate: {gate.value ? 'Pass' : 'Fail'}</div>
      <div data-testid="exp_test">
        an_experiment: {experiment.get('my_param', 'fallback')}
      </div>
    </div>
  );
}

function App() {
  return (
    <StatsigProvider
      sdkKey={YOUR_CLIENT_KEY}
      user={{ userID: 'a-user' }}
      options={{
        networkConfig: {
          // Optional – disable network requests in tests
          preventAllNetworkTraffic:
            typeof process !== 'undefined' && process.env['NODE_ENV'] === 'test',
        },
      }}
    >
      <Content />
    </StatsigProvider>
  );
}

import { render, screen } from '@testing-library/react';
import * as ReactBindings from '@statsig/react-bindings';

jest.mock('@statsig/react-bindings', () => ({
  ...jest.requireActual('@statsig/react-bindings'),
  useFeatureGate: () => ({ value: true }),
  useExperiment: () => ({ get: () => 'my_value' }),
}));

test('renders gate pass', async () => {
  render(<App />);
  const elem = await screen.findByTestId('gate_test');
  expect(elem.textContent).toContain('Pass');
});

test('renders experiment value', async () => {
  render(<App />);
  const elem = await screen.findByTestId('exp_test');
  expect(elem.textContent).toContain('my_value');
});

Session Replay

Install @statsig/session-replay and register the plugin to record user sessions.

import { StatsigProvider, useClientAsyncInit } from '@statsig/react-bindings';
import { StatsigSessionReplayPlugin } from '@statsig/session-replay';

function App() {
  const { client } = useClientAsyncInit(
   'client-KEY',
    { userID: 'a-user' },
    { plugins: [new StatsigSessionReplayPlugin()] },
  );

  return (
    <StatsigProvider client={client} loadingComponent={<div>Loading...</div>}>
      <div>Hello World</div>
    </StatsigProvider>
  );
}

Web Analytics / Auto Capture

Capture clicks and page views automatically with @statsig/web-analytics.

import { StatsigProvider, useClientAsyncInit } from '@statsig/react-bindings';
import { StatsigAutoCapturePlugin } from '@statsig/web-analytics';

function App() {
  const { client } = useClientAsyncInit(
   'client-KEY',
    { userID: 'a-user' },
    { plugins: [new StatsigAutoCapturePlugin()] },
  );

  return (
    <StatsigProvider client={client} loadingComponent={<div>Loading...</div>}>
      <div>Hello World</div>
    </StatsigProvider>
  );
}

Using Persistent Evaluations

Keep experiment variants stable across rerenders or user transitions by plugging in persistent storage. The React integration mirrors the JavaScript workflow and you can adapt the Next.js sample to your setup. Read more in Client Persistent Assignment.

SDK Quickstarts

SDK Concepts

Client SDKs

Server SDKs

More SDK Methods

Console API Reference

Statsig CLI

HTTP API Reference

Set Up the SDK

AI-powered Setup

Install Packages

Wrap Your App With `StatsigProvider`

Typical Project Structure

Use the SDK

Checking a Feature Flag/Gate

Reading a Dynamic Config

Getting a Layer/Experiment

Logging an Event

Parameter Stores

Manage Users

Updating User Properties

Loading State

React Hooks

Feature Gate Hooks

Dynamic Config Hooks

Experiment Hooks

Layer Hooks

Parameter Store Hooks

Log Events From Hooks

StatsigUser Hook

Direct Access to the Client

Client Initialization Hooks

Statsig Options

Testing

Session Replay

Web Analytics / Auto Capture

Using Persistent Evaluations

Additional Resources

​Set Up the SDK

​AI-powered Setup

​Install Packages

​Wrap Your App With StatsigProvider

​Typical Project Structure

​Use the SDK

​Checking a Feature Flag/Gate

​Reading a Dynamic Config

​Getting a Layer/Experiment

​Logging an Event

​Parameter Stores

​Manage Users

​Updating User Properties

​Loading State

​React Hooks

​Feature Gate Hooks

​Dynamic Config Hooks

​Experiment Hooks

​Layer Hooks

​Parameter Store Hooks

​Log Events From Hooks

​StatsigUser Hook

​Direct Access to the Client

​Client Initialization Hooks

​Statsig Options

​Testing

​Session Replay

​Web Analytics / Auto Capture

​Using Persistent Evaluations

​Additional Resources

Set Up the SDK

AI-powered Setup

Install Packages

Wrap Your App With `StatsigProvider`

Typical Project Structure

Use the SDK

Checking a Feature Flag/Gate

Reading a Dynamic Config

Getting a Layer/Experiment

Logging an Event

Parameter Stores

Manage Users

Updating User Properties

Loading State

React Hooks

Feature Gate Hooks

Dynamic Config Hooks

Experiment Hooks

Layer Hooks

Parameter Store Hooks

Log Events From Hooks

StatsigUser Hook

Direct Access to the Client

Client Initialization Hooks

Statsig Options

Testing

Session Replay

Web Analytics / Auto Capture

Using Persistent Evaluations

Additional Resources