> ## Documentation Index > Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # React Web SDK reference **The React Web SDK does not work in React Native projects** If you want to add LaunchDarkly to your React Native codebase, use the React Native SDK instead. The React Web SDK is intended for use in web applications, and the React Native SDK is specifically designed to run in mobile environments. To learn more, read [React Native SDK](/docs/sdk/client-side/react/react-native). 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. **SDK quick links** LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:
Resource Location
SDK API documentation [SDK API docs](https://launchdarkly.github.io/js-core/packages/sdk/react/docs/modules/client.html)
Supported SDK Versions [React Web SDK](/docs/sdk/concepts/supported-versions#react-web-sdk)
GitHub repository [js-core/packages/sdk/react](https://github.com/launchdarkly/js-core/tree/main/packages/sdk/react)
Sample application [React Web](/docs/sdk/client-side/react/react-web#example-app)
Published module [npm](https://www.npmjs.com/package/@launchdarkly/react-sdk)
Similar documentation for React Server Component support is available in [React Server Component support](#react-server-component-support). ## Get started After you complete the [Get started](/docs/home/getting-started) process, follow these instructions to start using the LaunchDarkly React Web SDK in your React code: * [Understand version compatibility](#understand-version-compatibility) * [Install the SDK](#install-the-sdk) * [Initialize the client](#initialize-the-client) * [Identify the context](#identify-the-context) * [Subscribe to flag changes](#subscribe-to-flag-changes) * [Access flag values](#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](/docs/sdk/client-side/javascript). 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](#hooks). ### Install the SDK Install the React Web SDK using `npm` or `yarn`. We recommend making the LaunchDarkly [observability plugins](/docs/sdk/observability) available as well. These plugins collect and send observability data to LaunchDarkly, including [metrics autogenerated from observability events](/docs/home/metrics/autogen/observability). 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: ```bash title="Installing with npm" lines wrap theme={null} npm install @launchdarkly/react-sdk npm install @launchdarkly/observability # optional observability plugin npm install @launchdarkly/session-replay # optional session replay plugin ``` ```bash title="Installing with yarn" lines wrap theme={null} yarn add @launchdarkly/react-sdk yarn add @launchdarkly/observability # optional observability plugin yarn add @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](/docs/home/flags/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. **React Web SDK credentials** The React Web SDK requires a client-side ID. Client-side IDs are specific to each project and environment. They are not secret, and you can include them in client-side code. Do not embed a server-side SDK key in a client-side application. You can find client-side IDs and project keys are on the **SDK keys** page under **Settings**. To learn more about key types, read [Keys](/docs/sdk/concepts/client-side-server-side#keys-and-credentials). If you connect the React Web SDK to the ldcli dev-server for local testing, use your project key instead of a client-side ID. Set all service endpoints to `http://localhost:8765`. If you use a client-side ID, the SDK connects to LaunchDarkly rather than the dev-server, which can result in CORS errors. 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`: ```js title="React Web SDK v4.0" maxLines=0 lines wrap theme={null} import { useInitializationStatus, createLDReactProvider } from '@launchdarkly/react-sdk'; const LDProvider = createLDReactProvider('your-client-side-id', { kind: 'user', key: 'user-key' }); function App() { const { status, error } = useInitializationStatus(); if (status === 'initializing') return
initializing
; if (status === 'failed') return
Error: {error?.message}
; return
Your application code
; } root.render(); ``` In addition to this recommended initialization route, we also provide a couple of alternative initialization processes for greater flexibility: * You can use [`createLDReactProviderWithClient`](https://launchdarkly.github.io/js-core/packages/sdk/react/docs/functions/client.createLDReactProviderWithClient.html) to more easily manage multiple SDK client instances. * You can use [`createClient`](https://launchdarkly.github.io/js-core/packages/sdk/react/docs/functions/client.createClient.html) 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: ```js title="JavaScript: app.js" lines wrap theme={null} // app.js import React, { useEffect } from 'react'; import { useLDClient } from '@launchdarkly/react-sdk'; export default function App() { const ldClient = useLDClient(); useEffect(() => { ldClient.identify({ key: 'example-context-key' }); }, []); return
Let your feature flags fly!
} ``` ```js title="JavaScript: index.js" maxLines=0 expandable lines wrap theme={null} // index.js import React from 'react'; import ReactDOM from 'react-dom/client'; import App from 'app.js'; import { createLDReactProvider } from '@launchdarkly/react-sdk'; const root = ReactDOM.createRoot(document.getElementById('root')); const LDProvider = createLDReactProvider('example-client-side-id', { kind: 'user', anonymous: true, }); root.render( ); ``` 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](/docs/sdk/features/identify#react). ### Subscribe to flag changes The React Web SDK will subscribe to individual flag `change` events when you use one of the [variation hooks](#single-flag-hooks) or the [variation details hooks](#single-flag-hooks-with-full-evaluation-detail). 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: ```js title="React Web SDK v4.0" lines wrap theme={null} import { createLDReactProvider } from '@launchdarkly/react-sdk'; const LDProvider = createLDReactProvider( 'example-client-side-id', { kind: 'user', key: 'example-user-key' }, { ldOptions: { streaming: false, // or `true` to enable }, }, ); ``` 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](/docs/sdk/features/flag-changes#javascript). ### 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](#single-flag-hooks). Here's how: ```js lines wrap theme={null} import { useBoolVariation } from '@launchdarkly/react-sdk'; const Home = () => { const showNewFeature = useBoolVariation('show-new-feature', false); return showNewFeature ?
Flag on
:
Flag off
; }; export default Home; ``` In this example, we set the default flag value for `show-new-feature` to `false`. After the SDK client initializes, a streaming connection is established and any changes to the `show-new-feature` value update the component. **Making feature flags available to this SDK** You must make feature flags available to client-side SDKs before the SDK can evaluate those flags. If an SDK tries to evaluate a feature flag that is not available, the context will receive the fallback value for that flag. To make a flag available to this SDK, check the **SDKs using Client-side ID** checkbox during flag creation, or toggle on the option in the flag's right sidebar. To make all of a project's flags available to this SDK by default, check the **SDKs using Client-side ID** checkbox on your project's [Flag settings page](/docs/home/account/edit-project). ## 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`](https://launchdarkly.github.io/js-core/packages/sdk/react/docs/interfaces/client.LDReactProviderOptions.html). ## 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: ```js title="React Web SDK v4.0" lines wrap theme={null} import { useBoolVariation, useStringVariation, useNumberVariation, useJsonVariation, } from '@launchdarkly/react-sdk'; const showNewFeature = useBoolVariation('show-new-feature', false); const theme = useStringVariation('ui-theme', 'light'); const maxItems = useNumberVariation('max-items', 10); 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: ```js title="React Web SDK v4.0" lines wrap theme={null} import { useBoolVariationDetail } from '@launchdarkly/react-sdk'; 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](https://github.com/launchdarkly/js-core/tree/main/packages/sdk/react/examples/hello-react). ## Events In v4.0 and later of the React Web SDK, the typed [variation hooks](#single-flag-hooks) and [variation detail hooks](#single-flag-hooks-with-full-evaluation-detail) send an evaluation event each time they evaluate a flag. To disable sending events, set the [`sendEvents`](https://launchdarkly.github.io/js-core/packages/sdk/react/docs/interfaces/client.LDReactClientOptions.html#sendEvents) configuration option to `false`. **Event behavior with the deprecated `useFlags` hook** The `useFlags` hook is deprecated in v4.0. To learn more, read [Flag keys and the deprecated `useFlags` hook](#flag-keys-and-the-deprecated-useflags-hook). If you are still using `useFlags`, the following event behavior applies: * In versions 2.27 and later, the SDK sends an evaluation event when your app accesses a flag from the `flags` object returned by `useFlags`, and when you call a variation method on the `LDClient`. * In versions 2.26 and earlier, you must make variation calls directly to send evaluation events. If you are using Experimentation, confirm that `reactOptions.sendEventsOnFlagRead` is set to `true` or is not specified. Setting it to `false` prevents evaluation events from being recorded. ## Do Not Track and ad blocking software The React Web SDK respects the [Do Not Track](https://www.eff.org/issues/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](https://support.launchdarkly.com/hc/en-us/articles/13689033183771-Browser-privacy-settings-block-analytic-events-to-LaunchDarkly). The React Web SDK respects the [Do Not Track](https://www.eff.org/issues/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.us`. To learn more, read [Browser privacy settings block analytic events to LaunchDarkly](https://support.launchdarkly.com/hc/en-us/articles/13689033183771-Browser-privacy-settings-block-analytic-events-to-LaunchDarkly). The React Web SDK respects the [Do Not Track](https://www.eff.org/issues/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.eu.launchdarkly.com`. To learn more, read [Browser privacy settings block analytic events to LaunchDarkly](https://support.launchdarkly.com/hc/en-us/articles/13689033183771-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](/docs/sdk/concepts/events). ## Flag keys and the deprecated `useFlags` hook The `useFlags` hook is deprecated in v4.0. We recommend migrating to the typed [variation hooks](#single-flag-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](/docs/home/infrastructure/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](/docs/home/flags/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](/docs/home/flags/code-references#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: ```js title="React Web SDK v4.0" lines wrap theme={null} import { createLDReactProvider } from '@launchdarkly/react-sdk'; const LDProvider = createLDReactProvider( 'example-client-side-id', { kind: 'user', key: 'example-user-key' }, { ldOptions: { useCamelCaseFlagKeys: false, }, }, ); ``` 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](https://github.com/launchdarkly/ld-find-code-refs/blob/main/docs/ALIASES.md#configuring-aliases) 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: ```js title="environments.ts" expandable lines wrap theme={null} // Single module, import anywhere in your app import { initLDReactContext, createClient, createLDReactProviderWithClient, } from '@launchdarkly/react-sdk'; export const ProdLDContext = initLDReactContext(); export const StagingLDContext = initLDReactContext(); const prodClient = createClient('prod-client-side-id', { kind: 'user', key: 'user-key' }); const stagingClient = createClient('staging-client-side-id', { kind: 'user', key: 'user-key' }); prodClient.start(); stagingClient.start(); export const ProdLDProvider = createLDReactProviderWithClient(prodClient, ProdLDContext); export const StagingLDProvider = createLDReactProviderWithClient(stagingClient, StagingLDContext); ``` ```js title="Root.tsx" lines wrap theme={null} function Root() { return ( ); } ``` ```js title="In any component" lines wrap theme={null} import { useBoolVariation } from '@launchdarkly/react-sdk'; import { ProdLDContext, StagingLDContext } from './environments'; function MyComponent() { const showInProd = useBoolVariation('my-feature', false, ProdLDContext); const showInStaging = useBoolVariation('my-feature', false, 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"](https://support.launchdarkly.com/hc/en-us/articles/12998125691419-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](https://react.dev/reference/rsc/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). **Quick links** React Server Component support is available as part of the open source React Web SDK. In addition to this reference guide, we provide React Server Component-specific source, API reference documentation, and a sample application:
Resource Location
API documentation [API docs](https://launchdarkly.github.io/js-core/packages/sdk/react/docs/modules/server.html)
GitHub repository [js-core](https://github.com/launchdarkly/js-core)
Sample application [hello-react-server](https://github.com/launchdarkly/js-core/tree/main/packages/sdk/react/examples/react-server-example)
Published module [npm](https://www.npmjs.com/package/@launchdarkly/react-sdk)
### 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: ```tsx title="React Web SDK v4.0" expandable lines wrap theme={null} import { init } from '@launchdarkly/node-server-sdk'; import { createLDServerSession } from '@launchdarkly/react-sdk/server'; const ldBaseClient = init(process.env.LAUNCHDARKLY_SDK_KEY!); // In your root Server Component (for example, app/layout.tsx or app/page.tsx) export default async function Page() { await ldBaseClient.waitForInitialization({ timeout: 10 }); const session = createLDServerSession(ldBaseClient, { kind: 'user', key: 'user-key', name: 'Sandy', }); const showFeature = await session.boolVariation('show-new-feature', false); return
{showFeature ? 'New Feature!' : 'Classic'}
; } ``` 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: ```js title="Create a server session" lines wrap theme={null} // app/page.tsx — create the session in a parent component import { createLDServerSession } from '@launchdarkly/react-sdk/server'; export default async function Page() { await ldBaseClient.waitForInitialization({ timeout: 10 }); createLDServerSession(ldBaseClient, { kind: 'user', key: 'user-key' }); return ; } ``` ```js title="Use a server session" lines wrap theme={null} // components/FeatureBanner.tsx — retrieve it in a nested component import { useLDServerSession } from '@launchdarkly/react-sdk/server'; export default async function FeatureBanner() { const session = useLDServerSession(); if (!session) return null; const banner = await session.stringVariation('banner-text', 'Welcome'); return

{banner}

; } ``` ### `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: ```js title="React Server Component behavior" lines wrap theme={null} import { createLDServerWrapper } from '@launchdarkly/react-sdk/server'; const session = createLDServerWrapper(ldBaseClient, context); ``` ## Supported features React Server Component support is available for the following LaunchDarkly SDK features: * [Bootstrapping](/docs/sdk/features/bootstrapping#react-server-wrapper) * [Flag variation evaluation](/docs/sdk/features/evaluating#react-server-component-support)