React Client SDK

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

Set Up the SDK

This page explains set up the sdk.

Install the SDK

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>
  );
}
```ruby

### Typical Project Structure

Most projects render a root component inside the provider.

```tsx
// 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>
  );
}
```text

```tsx
// 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

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

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

  </Tab>
  <Tab title="useClientAsyncInit">

```tsx
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>
);
```ruby

### Dynamic Config Hooks

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

```tsx
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>
);
```ruby

### Experiment Hooks

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

```tsx
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>
);
```text

### Layer Hooks

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

```tsx
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>
);
```text

### Parameter Store Hooks

```tsx
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>;
}
```sql

### Log Events From Hooks

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

const { logEvent } = useStatsigClient();

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

### StatsigUser Hook

```tsx
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>
);
```text

### Direct Access to the Client

```tsx
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

This page explains statsig options.

loggingEnabled

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.

disableLogging

boolean

deprecated

Use loggingEnabled: 'disabled' instead.

disableStableID

boolean

default:"false"

Skip generating a device-level Stable ID.

disableEvaluationMemoization

boolean

default:"false"

Recompute every evaluation instead of using the memoized result.

initialSessionID

string

Override the generated session ID.

enableCookies

boolean

default:"false"

Persist Stable ID in cookies for cross-domain tracking.

disableStorage

boolean

Prevent any local storage writes (disables caching).

networkConfig

NetworkConfig

Override network endpoints per request type.

environment

StatsigEnvironment

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

logLevel

LogLevel

default:"Warn"

Console verbosity.

loggingBufferMaxSize

number

default:"50"

Max events per log batch.

loggingIntervalMs

number

default:"10_000"

Interval between automatic flushes.

overrideAdapter

OverrideAdapter

Modify evaluations before returning them.

includeCurrentPageUrlWithEvents

boolean

default:"true"

Attach the current page URL to logged events.

disableStatsigEncoding

boolean

default:"false"

Send requests without Statsig-specific encoding.

logEventCompressionMode

LogEventCompressionMode

default:"Enabled"

Control compression for batched events.

disableCompression

boolean

deprecated

Use logEventCompressionMode instead.

dataAdapter

EvaluationsDataAdapter

Provide a custom data adapter to control caching/fetching.

customUserCacheKeyFunc

CustomCacheKeyGenerator

Override cache key generation for stored evaluations.

Network Config Options

api

string

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

Base URL for all requests (append /v1).

logEventUrl

string

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

Endpoint for event uploads.

logEventFallbackUrls

string[]

Fallback endpoints for event uploads.

networkTimeoutMs

number

default:"10000"

Request timeout in milliseconds.

preventAllNetworkTraffic

boolean

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

networkOverrideFunc

function

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

initializeUrl

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>
  );
}
```text

```tsx
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>
  );
}
```text

<webAnalyticsIntro/>

```tsx
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

AI SDKs

More SDK Methods

Console API Reference

Statsig CLI

HTTP API Reference

Set Up the SDK

Wrap Your App With `StatsigProvider`

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

Client Initialization Hooks

Statsig Options

Testing

Session Replay

Using Persistent Evaluations

Additional Resources

SDK Quickstarts

SDK Concepts

Client SDKs

Server SDKs

AI SDKs

More SDK Methods

Console API Reference

Statsig CLI

HTTP API Reference

​Set Up the SDK

​Wrap Your App With StatsigProvider

​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

​Client Initialization Hooks

​Statsig Options

​Testing

​Session Replay

​Using Persistent Evaluations

​Additional Resources

Set Up the SDK

Wrap Your App With `StatsigProvider`

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

Client Initialization Hooks

Statsig Options

Testing

Session Replay

Using Persistent Evaluations

Additional Resources