React Web SDK reference

Overview

This topic documents how to get started with the client-side React Web SDK, and links to reference information on all of the supported features.

Get started

After you complete the Get started process, follow these instructions to start using the LaunchDarkly React Web SDK in your React code:

• Understand version compatibility
• Install the SDK
• Initialize the client
• Identify the context
• Subscribe to flag changes
• Access flag values

Understand version compatibility

The React Web SDK is based on the JavaScript SDK. The React Web SDK builds on LaunchDarkly’s JavaScript SDK to provide a better integration for use in React applications. As a result, much of the JavaScript SDK functionality is also available for the React Web SDK to use. For a complete client-side JavaScript SDK reference, read JavaScript SDK reference.

The React Web SDK version 4.0 requires React version 18.0.0 or higher.

The LaunchDarkly React Web SDK versions 3.0 and higher are compatible with React version 16.3.3 and higher.

The LaunchDarkly React Web SDK versions 2.x are compatible with React version 16.3.0 and higher.

The LaunchDarkly React Web SDK offers eight custom hooks. If you want to use these, then you must use React version 18.0.0 or higher. To learn more, read Hooks.

Install the SDK

Install the React Web SDK using npm or yarn.

We recommend making the LaunchDarkly observability plugins available as well. These plugins collect and send observability data to LaunchDarkly, including metrics autogenerated from observability events. This means you can review session replay, error monitoring, logs, and traces from within the LaunchDarkly UI. They require the React Web SDK version 3.7 or later.

Here’s how:

$
npm install @launchdarkly/react-sdk
$
npm install @launchdarkly/observability # optional observability plugin
$
npm install @launchdarkly/session-replay # optional session replay plugin

Initialize the client

After you install the dependency, your code must initialize the React Web SDK before it can evaluate flags. To do this, we recommend using createLDReactProvider to create an SDK client provider and useInitializationStatus to determine the appropriate time to evaluate your flags.

createLDReactProvider relies on React’s Context API, which lets you access your flags from any level of your component hierarchy. The React Context API is unrelated to LaunchDarkly contexts.

To initialize the React Web SDK, you need your LaunchDarkly environment’s client-side ID and the context for which you want to evaluate flags. This authorizes your application to connect to a particular environment within LaunchDarkly.

The createLDReactProvider function initializes the React Web SDK and returns a Context Provider, which is a React component.

You must initialize createLDReactProvider at the app entry point, prior to rendering, to ensure that flags and the LaunchDarkly client are ready at the start of your React app lifecycle.

This provider enables the use of the new useInitializationStatus status hook, which you can use to react to initialization status updates. Typically, you would want to wait for the SDK initialization status to be complete before trying to evaluate flags.

Here’s how to initialize using createLDReactProvider:

1
import { useInitializationStatus, createLDReactProvider } from '@launchdarkly/react-sdk';
2
3
const LDProvider = createLDReactProvider('your-client-side-id', { kind: 'user', key: 'user-key' });
4
5
function App() {
6
  const { status, error } = useInitializationStatus();
7
  if (status === 'initializing') return <div> initializing </div>;
8
  if (status === 'failed') return <div> Error: {error?.message} </div>;
9
  return <div> Your application code </div>;
10
}
11
12
root.render(<LDProvider><App /></LDProvider>);

In addition to this recommended initialization route, we also provide a couple of alternative initialization processes for greater flexibility:

• You can use createLDReactProviderWithClient to more easily manage multiple SDK client instances.
• You can use createClient to manage your own client instance without React context.

Identify the context

After initialization is complete, your flags and the client are available at the start of your React app lifecycle. This ensures your app does not flicker due to flag changes at startup time.

In the React Web SDK, all SDK clients must be initialized with an initial context. If you do not know which context to initialize the SDK with, then we recommend initializing the SDK with an anonymous context. You can use the identify function to change this context at any time.

Here’s how to identify the context after initialization:

1
// app.js
2
import React, { useEffect } from 'react';
3
import { useLDClient } from '@launchdarkly/react-sdk';
4
5
export default function App() {
6
  const ldClient = useLDClient();
7
8
  useEffect(() => {
9
    ldClient.identify({ key: 'example-context-key' });
10
  }, []);
11
12
  return <div>Let your feature flags fly!</div>
13
}

This example initializes the SDK client with an anonymous context. It does not use useInitializationStatus to wait for the client to finish initializing before calling identify, so the context change is requested immediately. To learn more, read Identifying and changing contexts.

Subscribe to flag changes

The React Web SDK will subscribe to individual flag change events when you use one of the variation hooks or the variation details hooks. This will automatically open a streaming connection.

In some cases, streaming may not be necessary. For example, if you reload your entire application on each update, you will get all the flag values again when the client is re-initialized. In this situation, we recommend disabling streaming mode. To disable streaming mode, set streaming: false on the ldOptions you pass to createLDReactProvider. When streaming is disabled, no live updates occur.

In other cases, streaming may be required. Subscribing to streaming is the only way to receive real-time updates. If you determine that streaming is necessary for your application, we recommend explicitly enabling streaming mode by setting streaming: true on ldOptions.

Here’s how to configure streaming explicitly:

1
import { createLDReactProvider } from '@launchdarkly/react-sdk';
2
3
const LDProvider = createLDReactProvider(
4
  'example-client-side-id',
5
  { kind: 'user', key: 'example-user-key' },
6
  {
7
    ldOptions: {
8
      streaming: false, // or `true` to enable
9
    },
10
  },
11
);

This behavior is different from the JavaScript SDK, where you need to opt in to event listening. To learn more about how the JavaScript SDK handles flag change events, read Subscribing to flag changes.

Access flag values

After your code has initialized the React Web SDK, your primary means to access flag evaluation values is through our variation hooks.

Here’s how:

1
import { useBoolVariation } from '@launchdarkly/react-sdk';
2
3
const Home = () => {
4
  const showNewFeature = useBoolVariation('show-new-feature', false);
5
6
  return showNewFeature ? <div>Flag on</div> : <div>Flag off</div>;
7
};
8
9
export default Home;

Configuration options

The createLDReactProvider function takes two required parameters: a client-side ID and an initial context. You can optionally specify a third LDReactProviderOptions parameter that lets you further configure your provider.

To learn more, read LDReactProviderOptions.

Hooks

The React Web SDK offers eight custom hooks.

Single-flag hooks

There are four single-flag hooks:

• useBoolVariation
• useStringVariation
• useNumberVariation
• useJsonVariation

These typed single-flag hooks re-render only when that specific flag changes.

We recommend using these hooks for evaluating individual flags. They are explicitly typed, with no generic type parameter needed.

The naming convention aligns with the LaunchDarkly React Native SDK and other LaunchDarkly SDKs, making the API consistent across platforms.

Here’s how to use them:

1
import {
2
  useBoolVariation,
3
  useStringVariation,
4
  useNumberVariation,
5
  useJsonVariation,
6
} from '@launchdarkly/react-sdk';
7
8
const showNewFeature = useBoolVariation('show-new-feature', false);
9
const theme          = useStringVariation('ui-theme', 'light');
10
const maxItems       = useNumberVariation('max-items', 10);
11
const config         = useJsonVariation('my-config', {});

Single-flag hooks with full evaluation detail

There are four single-flag hooks that provide full evaluation details:

• useBoolVariationDetail
• useStringVariationDetail
• useNumberVariationDetail
• useJsonVariationDetail

These single-flag hooks return the full evaluation detail, including value, variationIndex, and evaluation reason, re-rendering only when that specific flag changes.

Use these hooks when you need the evaluation reason but don’t want to subscribe to every flag change.

Here’s how to use them:

1
import { useBoolVariationDetail } from '@launchdarkly/react-sdk';
2
3
const { value, variationIndex, reason } = useBoolVariationDetail('example-flag-key', false);

Example app

For a working single-page app with React and react-router, use this example app.

Events

In v4.0 and later of the React Web SDK, the typed variation hooks and variation detail hooks send an evaluation event each time they evaluate a flag. To disable sending events, set the sendEvents configuration option to false.

Do Not Track and ad blocking software

The React Web SDK respects the Do Not Track header. If an end user has Do Not Track enabled in their browser, the SDK does not send analytics events for flag evaluations or metrics to events.launchdarkly.com. To learn more, read Browser privacy settings block analytic events to LaunchDarkly.

In addition, ad blocking software may block analytics events from being sent. This does not impact feature flag evaluations. To learn more about the events SDKs send to LaunchDarkly, read Analytics events.

Flag keys and the deprecated useFlags hook

The useFlags hook is deprecated in v4.0. We recommend migrating to the typed variation hooks. The information in this section only applies if you are still using useFlags.

LaunchDarkly primarily identifies feature flags by a key which must contain only alphanumeric characters, dots (.), underscores (_), and dashes (-). These keys are used in the SDKs to identify flags, and in LaunchDarkly’s REST API.

However, in JavaScript, accessing keys containing . and - requires the bracket operator. Instead of requiring this, the React Web SDK automatically changes all flag keys to camel case by default when you use useFlags. A flag with key dev-flag-test is accessible as flags.devFlagTest.

Automatically changing flag keys to camel case poses some problems:

• It is possible to induce a key collision if there are multiple LaunchDarkly flag keys which resolve to the same camel-case key. For example, dev-flag-test and dev.flag.test are unique keys in LaunchDarkly, but the React Web SDK changes them to the same camel-case key.
• If a flag key contains three or more capital letters in a row, the React Web SDK automatically converts all letters between the first and last capital letter to lower case. For example, the SDK converts a flag with the key devQAFlagTest to devQaFlagTest. If you use devQAFlagTest with the useFlags() hook, the SDK will not find the flag.
• LaunchDarkly’s code references tool expects your source code to reference the exact key, not a camel-case equivalent. The tool does not detect keys that were automatically changed to camel-case. However, you can configure an alias to ensure that the code references tool detects the camel-case equivalents. To learn more, read Find flag aliases.
• Because the camel-case functionality is implemented in the React Web SDK instead of in the underlying JavaScript SDK, the underlying client object and functionality provided by the JavaScript SDK reflect flag keys in their original format. Only React-specific contexts such as your injected props use camel case.

To disable the SDK’s automatic camel-case feature, set the useCamelCaseFlagKeys option to false when you initialize the SDK. Like useFlags, this option is deprecated and will be removed in a future major version. The typed variation hooks always use the original flag key, so they are not affected by this option.

Here’s how to disable the automatic camel-case feature:

1
import { createLDReactProvider } from '@launchdarkly/react-sdk';
2
3
const LDProvider = createLDReactProvider(
4
  'example-client-side-id',
5
  { kind: 'user', key: 'example-user-key' },
6
  {
7
    ldOptions: {
8
      useCamelCaseFlagKeys: false,
9
    },
10
  },
11
);

With this option in place, you can access your dev-flag-test flag using bracket notation, for example, flags['dev-flag-test'].

If you keep the automatic camel-case feature enabled and you want to use LaunchDarkly’s code references tool, you can configure alias support to find camel-cased flags. To do so, use the value camelCase for the alias settings.

Multi-environment support

The React Web SDK supports multiple LaunchDarkly environments in the same React tree. Each environment gets its own React context, provider, and client. Hooks read from whichever context you pass.

Here is an example:

1
// Single module, import anywhere in your app
2
import {
3
  initLDReactContext,
4
  createClient,
5
  createLDReactProviderWithClient,
6
} from '@launchdarkly/react-sdk';
7
8
export const ProdLDContext    = initLDReactContext();
9
export const StagingLDContext = initLDReactContext();
10
11
const prodClient    = createClient('prod-client-side-id',    { kind: 'user', key: 'user-key' });
12
const stagingClient = createClient('staging-client-side-id', { kind: 'user', key: 'user-key' });
13
prodClient.start();
14
stagingClient.start();
15
16
export const ProdLDProvider    = createLDReactProviderWithClient(prodClient,    ProdLDContext);
17
export const StagingLDProvider = createLDReactProviderWithClient(stagingClient, StagingLDContext);

Each client’s lifecycle, including identify(), is independent. Call it on each client when the user context changes.

Troubleshooting

This section describes common issues you might encounter when using the React Web SDK and how to resolve them.

Network error

If your application logs show the error LaunchDarklyFlagFetchError: network error, there may be a problem with network connectivity between your SDK and LaunchDarkly.

For steps to resolve this issue, read the LaunchDarkly Knowledge Base article Error “LaunchDarklyFlagFetchError: network error”.

CORS errors in local development

If you see CORS errors in the browser while using the ldcli dev-server, check your SDK configuration. The React Web SDK must use your project key as the credential and all service endpoints must point to http://localhost:8765.

If you use a client-side ID instead of the project key, the SDK connects to LaunchDarkly rather than the dev-server. This prevents the SDK from retrieving local flag values and can produce CORS errors.

React Server Component support

As of version 4.0 of the React Web SDK, React Server Components are supported. You can perform flag evaluation in React Server Components.

This behavior is available as a lightweight wrapper around a server-side SDK that supports enabling frontend changes.

You must initialize a separate server-side SDK to interface with React Server Component features. To learn more about the server-side SDKs that support React Server Components, read React Server Component version compatibility.

React Server Component version compatibility

These behaviors work with the following React versions:

• React version 19.0.0 or higher

Create a wrapped server-side SDK client

This functionality wraps a server-side SDK and makes flag values available to React Server Components on a per-request basis.

Here’s how:

1
import { init } from '@launchdarkly/node-server-sdk';
2
import { createLDServerSession } from '@launchdarkly/react-sdk/server';
3
4
const ldBaseClient = init(process.env.LAUNCHDARKLY_SDK_KEY!);
5
6
// In your root Server Component (for example, app/layout.tsx or app/page.tsx)
7
export default async function Page() {
8
  await ldBaseClient.waitForInitialization({ timeout: 10 });
9
10
  const session = createLDServerSession(ldBaseClient, {
11
    kind: 'user',
12
    key: 'user-key',
13
    name: 'Sandy',
14
  });
15
16
  const showFeature = await session.boolVariation('show-new-feature', false);
17
  return <div>{showFeature ? 'New Feature!' : 'Classic'}</div>;
18
}

In this example, we are wrapping a Node Server SDK and using it to create a React Server Component from the show-new-feature boolean flag.

Unique behaviors

Several behaviors are only available as part of React Server Component support.

createLDServerSession and useLDServerSession

This creates a per-request evaluation scope by binding a server SDK client to a specific context. The session is cached using React’s cache() API, so each request gets its own isolated instance. This also enables useLDServerSession() to retrieve the session from nested React Server Components.

Here is an example:

1
// app/page.tsx — create the session in a parent component
2
import { createLDServerSession } from '@launchdarkly/react-sdk/server';
3
4
export default async function Page() {
5
  await ldBaseClient.waitForInitialization({ timeout: 10 });
6
  createLDServerSession(ldBaseClient, { kind: 'user', key: 'user-key' });
7
8
  return <FeatureBanner />;
9
}

createLDServerWrapper

This functions identically to createLDServerSession, but does not cache the session. Use this when you want manual lifecycle control or to avoid React’s cache() API.

This is an advanced behavior. Sessions created with createLDServerWrapper are not retrievable by useLDServerSession(). Instead, you must pass the session through props or module scope yourself.

Here is an example:

1
import { createLDServerWrapper } from '@launchdarkly/react-sdk/server';
2
3
const session = createLDServerWrapper(ldBaseClient, context);

Supported features

React Server Component support is available for the following LaunchDarkly SDK features:

• Bootstrapping
• Evaluating flags