LaunchDarkly Developer Documentation

Get started in under 30 minutes.
LaunchDarkly provides feature flags as a service for Java · Python · Ruby · Go · Node.js · PHP · .NET. Control feature launches -- who sees what and when -- without multiple code deploys. Easy dashboard for phased rollouts, targeting and segmenting.
Need more help? write us at support@launchdarkly.com

Get Started    Documentation

React SDK Reference

This reference guide documents all of the methods available in our client-side React SDK, and explains in detail how these methods work. If you want to dig even deeper, our SDKs are open source — head to the React SDK code in our JavaScript SDK GitHub repository to look under the hood. The online API docs contain the programmatic definitions of every type and method.

React SDK is based on the JavaScript SDK

The React SDK builds on top of 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 use by the React SDK. For a complete client-side JavaScript SDK reference, please refer to our documentation.

Requires React 16.3.0 or later

This SDK uses the Context API, which requires React version 16.3.0 or later. Please note that you must use a newer version if you wish to additionally use the Hooks API -- see the "Hooks" section below for more information.

Getting started

Building on top of our Quickstart guide, the following steps will get you started with using the LaunchDarkly SDK in your React code.

You can use either npm or yarn to install the React SDK:

npm i --save launchdarkly-react-client-sdk
yarn add launchdarkly-react-client-sdk

Once the dependency is installed, you'll want to initialize the LaunchDarkly client. To create a client instance, you need your environment's client-side ID (available on your account settings page). Client-side IDs are not secret-- they can be safely exposed in your client-side code.

withLDProvider

The React SDK relies on the Context API to make it easy for you to access your flags from any level of your component hierarchy. The withLDProvider function initializes the JavaScript SDK, and wraps your root component in a Context.Provider:

import { withLDProvider } from 'launchdarkly-react-client-sdk';

const App = () =>
  <div>
    <Home />
  </div>;

export default withLDProvider({ 
  clientSideID: 'your-client-side-id',
  user: {
    "key": "aa0ceb",
    "name": "Grace Hopper",
    "email": "gracehopper@example.com"
  },
  options: { /* ... */ }
})(App);

Customizing your client can be done via the options field. See the JavaScript SDK reference for all the available options.

Note that the React SDK automatically subscribes to flag change events; this is unlike the JavaScript SDK Reference where customers need to opt in to event listening. Consequently, in the React SDK, streaming mode is enabled by default. To disable streaming mode, specify a streaming: false attribute in your options object.

withLDConsumer

The return of withLDConsumer is a wrapper function that takes your component and returns a wrapper component with the injected props, flags & ldClient.

import { withLDConsumer } from 'launchdarkly-react-client-sdk';

const Home = ({ flags, ldClient /*, ...otherProps */ }) => {
	// You can call any of the methods from the JavaScript SDK
  // ldClient.identify({...})
  
  return flags.devTestFlag ? <div>Flag on</div> : <div>Flag off</div>;
};

export default withLDConsumer()(Home);

Hooks

The React SDK offers two custom hooks which you can use as an alternative to withLDConsumer: useFlags and useLDClient.

Requires React 16.8.0 or later

This SDK uses the Hooks API, which requires React version 16.8.0 or later.

useFlags is a custom hook which returns all feature flags. It uses the useContext primitive to access the LaunchDarkly context set up by withLDProvider. You will still need to use the withLDProvider higher-order component at the root of your application to initialize the React SDK and populate the context with LDClient and your flags.

useLDClient is the second custom hook which returns the underlying LaunchDarkly JavaScript SDK client object. Like the useFlags custom hook, useLDClient also uses the useContext primitive to access the LaunchDarkly context set up by withLDProvider. You will still need to use the withLDProvider higher-order component to initialize the React SDK to use this custom hook.

import React from 'react';
import { useFlags, useLDClient } from 'launchdarkly-react-client-sdk';

const HooksDemo = () => {
  const { devTestFlag } = useFlags();
  const ldClient = useLDClient();
  
  const onLoginSuccessful = () => ldClient.identify({ key: 'aa0ceb' });

  return (
    <div>{devTestFlag ? 'Flag on' : 'Flag off'}</div>
  );
};

export default HooksDemo;

Users

All user-related functionality provided by the JavaScript SDK is equally accessible in the React SDK. Refer to the users, private user attributes, and anonymous users sections of the JavaScript SDK reference guide for more information.

Flag keys

LaunchDarkly primarily identifies feature flags by a key which must only contain alphanumeric characters, dots (.), underscores (_), and dashes (-). These keys are used across all of LaunchDarkly's APIs as well as in the SDKs to identify flags.

However, keys in this format are slightly inconvenient to access in JavaScript and React as they cannot be accessed with the dot notation. As a result, the React SDK automatically camel-cases all flag keys. A flag with key dev-flag-test would be accessible as flags.devFlagTest.

Automatically camel-casing flag keys poses some problems, though. For one thing, it is possible to induce a key collision if there are multiple LaunchDarkly flag keys which resolve to the same camel-cased key. For example, dev-flag-test and dev.flag.test would be considered unique keys on LaunchDarkly yet the React SDK would consider them to have the same camel-cased keys. Secondly, our Git code references tool expects your source code to reference the exact key -- not a camel-cased equivalent -- and as a result, the tool does not support detecting references of keys that were automatically camel-cased.

To disable the SDK's automatic camel-casing feature, you can provide withLDProvider with the reactOptions.useCamelCaseFlagKeys property as shown in the following example. This is supported in versions 2.13.0 and later of the React SDK.

export default withLDProvider({ 
  clientSideID: 'your-client-side-id',
  user: {
    "key": "aa0ceb",
    "name": "Grace Hopper",
    "email": "gracehopper@example.com"
  },
  reactOptions: { 
    useCamelCaseFlagKeys: false
  }
})(App);

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

Example App

Check the example for a fully working single page app with react and react-router. You'll need to enter your clientSideId in the client root app file and create a flag with key dev-test-flag in your dashboard before running the example.

Alternatives from the community

Third-party developers have created their own React interfaces for the LaunchDarkly JavaScript SDK:


React SDK Reference


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.