React SDK reference

Overview

This reference guide documents all of the methods available in the client-side React SDK, and explains in detail how these methods work. LaunchDarkly's SDKs are open source. To learn more, read React SDK code in the JavaScript SDK GitHub repository. The online API docs contain the programmatic definitions of every type and method. You can also try this SDK out by cloning and running a sample application.

You can use LaunchDarkly in a Gatsby application with our Gatsby plugin.

Getting started

After you complete the Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your React code.

To install the React SDK, you need your LaunchDarkly environment's client-side ID, available in the Projects tab of your account settings page. Be sure to use a client-side ID. Never embed a server-side SDK key into a mobile application.

To begin using the LaunchDarkly SDK in your React code:

1. Use either npm or yarn to install the React SDK:

1npm i --save launchdarkly-react-client-sdk
COPY

2. After you install the dependency, initialize the React SDK. You can initialize the React SDK in one of two ways:

• Using the asyncWithLDProvider function
• Using the withLDProvider function

Both rely on React's Context API which lets you access your flags from any level of your component hierarchy. Both functions accept a ProviderConfig object used to configure the React SDK.

Initializing asyncWithLDProvider

The asyncWithLDProvider function initializes the React SDK and returns a provider which is a React component. It is an async function.

Here's how to initialize asyncWithLDProvider:

1import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';
2
3(async () => {
4  const LDProvider = await asyncWithLDProvider({
5    clientSideID: 'your-client-side-id',
6    user: {
7      "key": "aa0ceb",
8      "name": "Grace Hopper",
9      "email": "gracehopper@example.com"
10    },
11    options: { /* ... */ }
12  });
13
14  render(
15    <LDProvider>
16      <YourApp />
17    </LDProvider>,
18    document.getElementById('reactDiv'),
19  );
20})();
COPY

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

withLDProvider

The withLDProvider function initializes the React SDK and wraps your root component in a Context.Provider:

1import { withLDProvider } from 'launchdarkly-react-client-sdk';
2
3export default withLDProvider({
4  clientSideID: 'your-client-side-id',
5  user: {
6    "key": "aa0ceb",
7    "name": "Grace Hopper",
8    "email": "gracehopper@example.com"
9  },
10  options: { /* ... */ }
11})(YourApp);
COPY

Customize your client from the options field. To learn more, read the JavaScript SDK reference.

The React SDK automatically subscribes to flag change events. This is different from the JavaScript SDK, where customers need to opt in to event listening. To learn more, read Subscribing to flag changes.

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 value of withLDConsumer is a wrapper function that takes your component and returns a React component injected with flags & ldClient as props.

Here's how:

1import { withLDConsumer } from 'launchdarkly-react-client-sdk';
2
3const Home = ({ flags, ldClient /*, ...otherProps */ }) => {
4  // You can call any of the methods from the JavaScript SDK
5  // client.identify({...})
6
7  return flags.devTestFlag ? <div>Flag on</div> : <div>Flag off</div>;
8};
9
10export default withLDConsumer()(Home);
COPY

Configuring the React SDK

The ProviderConfig object configures the React SDK. The only mandatory property is the client-side ID. All other properties are optional.

These are the properties:

• clientSideID: This is your project and environment specific client-side ID. This property is mandatory.

• user: A LaunchDarkly user object. This property is optional unless you are initializing in secure mode, in which case it is mandatory.

• options: LaunchDarkly JavaScript SDK initialization options. This property is optional.

• reactOptions: This property is specific to the React SDK. You can use this option to disable automatic camel casing of flag keys when using the React SDK. This property is optional.

• deferInitialization: This property allows SDK initialization to be deferred until the user property is defined.

  By deferring SDK initialization, you defer all steps which take place as part of SDK initialization, including reading flag values from local storage and sending the SDK's ready event.

  The one exception to this rule is that the SDK continues to load bootstrapped flag values as long as the bootstrapped values are provided as a map of flag keys and values. As mentioned above, if indicated that the SDK should bootstrap flags from local storage, this will not happen until the SDK initializes.

• flags: If specified, the React SDK will only subscribe for updates to these flags. When this property is unspecified, the React SDK subscribes to all flags. This property is optional.

  Specify the flags property as a map of flag keys and values. The flag keys must be in their original form (as known to LaunchDarkly) rather than in their camel-cased form. Each flag's value is passed along to the resulting JS SDK variation invocation and used as the flag's default value in the case of an error.

The following is an example ProviderConfig object including each of the above properties:

1{
2  clientSideID: "your-client-side-id",
3  user: {
4    key: "aa0ceb",
5    name: "Grace Hopper",
6    email: "gracehopper@example.com"
7  },
8  options: {
9    bootstrap: "localStorage"
10  },
11  reactOptions: {
12    useCamelCaseFlagKeys: false
13  },
14  deferInitialization: false,
15  flags: {
16    "my-bool-flag": true,
17    "my-int-flag": 5
18  }
19}
COPY

Hooks

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

useFlags is a custom hook which returns all feature flags. It uses the useContext primitive to access the LaunchDarkly context set up by asyncWithLDProvider or withLDProvider. You still must use the asyncWithLDProvider or 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 asyncWithLDProvider or withLDProvider. You still must use the asyncWithLDProvider or the withLDProvider higher-order component to initialize the React SDK to use this custom hook.

For an example of how to use a custom hook, read HooksDemo.

Flag keys

LaunchDarkly primarily identifies feature flags by a key which must contain only 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, JavaScript and React cannot access keys with a dot notation, so the React SDK automatically changes all flag keys to camel case. A flag with key dev-flag-test is accessible as flags.devFlagTest.

Automatically changing flag keys to camel case poses some problems:

1. 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 SDK changes them to the same camel-case key.
2. If a flag key contains three or more capital letters in a row, the 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 does not find the flag.
3. 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.
4. Because the camel-case functionality is implemented in the React 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, provide asyncWithLDProvider or 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.

If the automatic camel-case feature is 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.

Here's how to configure alias:

1export default withLDProvider({
2  clientSideID: 'your-client-side-id',
3  reactOptions: {
4    useCamelCaseFlagKeys: false
5  }
6})(App);
COPY

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

Run this example for a fully working single page app with React and react-router. You must 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.