{"id":11228,"library":"launchdarkly-react-client-sdk","title":"LaunchDarkly React Client SDK","description":"The `launchdarkly-react-client-sdk` is the official client-side SDK for integrating LaunchDarkly feature flags into React applications. It leverages React's Context API and Hooks to provide a convenient way to access flag values and the LaunchDarkly client instance throughout a component tree. The current stable version is 3.9.0. This SDK typically sees several releases per year, often driven by updates to the underlying `js-client-sdk` and new React features. Key differentiators include its tight integration with React's component lifecycle, providing hooks like `useFlags` and `useLDClient`, and simplifying prop drilling for feature flags. It's designed for modern React development, compatible with React 16.3.0+, with Hooks requiring 16.8.0+.","status":"active","version":"3.9.0","language":"javascript","source_language":"en","source_url":"git://github.com/launchdarkly/react-client-sdk","tags":["javascript","launchdarkly","launch","darkly","react","sdk","bindings","typescript"],"install":[{"cmd":"npm install launchdarkly-react-client-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add launchdarkly-react-client-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add launchdarkly-react-client-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React application integration.","package":"react","optional":false},{"reason":"Peer dependency for React application integration.","package":"react-dom","optional":false}],"imports":[{"note":"This is the primary Higher-Order Component for initializing the SDK and making it available to your React app. ESM is preferred for modern React projects.","wrong":"const { withLDProvider } = require('launchdarkly-react-client-sdk');","symbol":"withLDProvider","correct":"import { withLDProvider } from 'launchdarkly-react-client-sdk';"},{"note":"A React Hook to access all available flag values for the current user context. Requires React 16.8.0 or later.","symbol":"useFlags","correct":"import { useFlags } from 'launchdarkly-react-client-sdk';"},{"note":"A React Hook to get the underlying LaunchDarkly client instance for advanced operations like tracking events or identifying users. Requires React 16.8.0 or later.","symbol":"useLDClient","correct":"import { useLDClient } from 'launchdarkly-react-client-sdk';"},{"note":"Use this function for scenarios where you need to pre-initialize the LaunchDarkly client asynchronously before rendering your React application.","symbol":"asyncWithLDProvider","correct":"import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';"}],"quickstart":{"code":"import React from 'react';\nimport { withLDProvider, useFlags } from 'launchdarkly-react-client-sdk';\n\nconst clientSideId = process.env.REACT_APP_LD_CLIENT_SIDE_ID ?? '';\n\nif (!clientSideId) {\n  console.error('LaunchDarkly Client-side ID is not set. Please set REACT_APP_LD_CLIENT_SIDE_ID in your environment variables.');\n}\n\ninterface MyComponentProps {\n  // any props for your component\n}\n\nconst MyFeatureComponent: React.FC<MyComponentProps> = () => {\n  const { myFeatureFlag, anotherFlag } = useFlags();\n\n  return (\n    <div>\n      <h1>My Application</h1>\n      {myFeatureFlag ? (\n        <p>Feature is ON! Displaying content for the feature.</p>\n      ) : (\n        <p>Feature is OFF. Default content.</p>\n      )}\n      {anotherFlag && <p>Another flag is also ON!</p>}\n    </div>\n  );\n};\n\nconst MyWrappedComponent = withLDProvider({\n  clientSideId: clientSideId,\n  user: { key: 'example-user', anonymous: true },\n  options: { \n    evaluationReasons: true \n  }\n})(MyFeatureComponent);\n\nexport default MyWrappedComponent;\n","lang":"typescript","description":"This quickstart initializes the LaunchDarkly SDK using `withLDProvider`, setting up an anonymous user and then demonstrating how to retrieve flag values within a functional component using the `useFlags` hook. It includes basic error handling for a missing client-side ID."},"warnings":[{"fix":"Always use the 'Client-side ID' found in your LaunchDarkly project settings. Ensure you are not exposing server-side SDK keys in client-side code.","message":"The React SDK requires a 'Client-side ID', not an 'SDK key' or 'Mobile key', for initialization. Using the wrong key will prevent the SDK from connecting.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify flag settings in the LaunchDarkly dashboard. If the flag is not client-side enabled, it will always return the default value provided in your code.","message":"For any feature flag to be accessible in the client-side React SDK, the 'Make this flag available to client-side SDKs' checkbox must be enabled on the flag's settings page in the LaunchDarkly dashboard.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your project's `react` and `react-dom` packages to version 16.8.0 or higher. For older React versions, you must use the Higher-Order Component approach without hooks.","message":"Using React Hooks (e.g., `useFlags`, `useLDClient`) or `asyncWithLDProvider` requires React version 16.8.0 or later. Earlier versions of React will result in runtime errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"This change is a fix for compatibility. If you are on an older version and facing issues in older browsers with newer JS syntax, ensure your build process targets ES2015 or earlier, or upgrade to v3.3.2+.","message":"From `launchdarkly-react-client-sdk` v3.3.2 onwards, the build target for ESBuild was explicitly set to ES2015 to ensure broader browser compatibility, overriding potential `tsconfig.json` defaults.","severity":"breaking","affected_versions":">=3.3.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `useFlags` and `useLDClient` are only called within functional React components. Verify `react` and `react-dom` versions are 16.8.0 or higher.","cause":"Attempting to use `useFlags` or `useLDClient` outside a functional React component or with an incompatible React version.","error":"Error: React hooks can only be called inside of the body of a function component. This could happen for one of the following reasons: 1. You might have mismatching versions of React and the renderer (such as React DOM) 2. You might be breaking the Rules of Hooks"},{"fix":"Ensure `clientSideId` is correctly passed to `withLDProvider` or `asyncWithLDProvider`, typically loaded from environment variables (e.g., `process.env.REACT_APP_LD_CLIENT_SIDE_ID`).","cause":"The `clientSideId` property was not provided or was an empty string during the initialization of `withLDProvider` or `asyncWithLDProvider`.","error":"LaunchDarkly: clientSideId must be specified."},{"fix":"Ensure the SDK is fully initialized by checking `isInitialized` from the provider or by using the `waitForInitialization` option. Also, verify the flag exists and is enabled for client-side SDKs in the LaunchDarkly dashboard.","cause":"Attempting to access a flag value from the `ldClient` or `useFlags` before the SDK has fully initialized or if the flag is not found/enabled for client-side SDKs.","error":"Cannot read properties of undefined (reading 'variation')"}],"ecosystem":"npm"}