README.md

react-ld

Pass Launch Darkly feature flags through your React application.

Takes a Launch Darkly instantiated client in a provider and enables easy access to feature flags throughout your React application.

Most Launch Darkly React libraries instantiate the client inside the React component. This gives an application less flexibility and control, which can impose constraints given the API provided by the library and you can't pass the client around your application if you have the need in a scaled application.

This library handles just the React part so you don't have to.

Install

Install with yarn

yarn add react-ld

or with npm

npm i react-ld

Usage

// Main.js
import React from 'react';
import ReactDOM from 'react-dom';
import { initialize } from 'launchdarkly-js-client-sdk';
import { LdProvider } from 'react-ld';

const LdClient = initialize('my-key', ...otherArgs);

ReactDOM.render(
  <LdProvider client={LdClient}>
    <App />
  </LdProvider>
);

// SomeComponent.js
import React from 'react';
import { useLdFlag } from 'react-ld';

const SomeComponent = () => {
  const myFeature = useLdFlag('myFeature');

  return (
    <div>
      {myFeature ? 'true' : 'false'}
    </div>
  );
};

// AnotherComponent.js
import React from 'react';
import { LdFeature } from 'react-ld';

const SomeComponent = () => (
  <>
    <LdFeature feature="myFeature">
      <VariationA>
    </LdFeature>
    <LdFeature feature="myFeature" deprecation>
      <VariationB>
    </LdFeature>
  </>
);

API

LdProvider

Top level provider component that will cascade feature flags through your React application.

Props	Type	Default	Description
children	React.Node	null	The react tree that will read flag values
client*	instaceof LD client	undefined	The LD client instantiated with settings of your choice
async	boolean	false	By default LDProvider will wait for the client to be ready before rendering the React tree. Enabling async mode will ignore the client status and render the tree immediately
stubbedFlags	{ [key: string]: any }	undefined	Accepts an object of properties that will override what may be provided by an LD client and instead pass the values of the object as the flags

LdFeature

This is the simplest way to render a feature flagged component when you don't need any extra logic.

Props	Type	Default	Description
children	React.Node	null	The component to render if the condition is true
feature*	string	undefined	The name of the feature flag
deprecation	boolean	false	By default if the flag evaluates to true, the child component will render. But you may want to do the reverse and enable an older version of a feature if the flag is false, which can be done by setting this prop to true
fallback	React.Node	null	If async mode is enabled, fallback will be rendered when the flags have not yet been defined

LdMultivariate

If your flag returns you a multivariate value, you can use this component instead of LdFeature. Which instead of rendering React.Node as the children, it instead expects a function that will be passed the multivariate value.

return (
  <LdMultivariate feature="my-feature">
    {(variation) => {
      if (variation === 'yes') return <YesComp />
      if (variation === 'no') return <NoComp />
      return <MaybeComp />
    }}
  </LdMultivariate>
)

children: (variation: any) => React.Node, feature: string,

Props	Type	Default	Description
children*	(variation: any) => React.Node	undefined	Render prop that will be passed the resulting variation that expects a React component to be returned
feature*	string	undefined	The name of the feature flag

useLdFlag

Alternatively to LdFeature or LdMultivariate, you may want to use hooks instead which can be helpful when you want to decide if you want to render a feature programmatically or you want to evaluate multiple flags together instead of nesting a large tree of components.

Props	Type	Default	Description
name*	string	undefined	The name of the feature flag
fallback	boolean	false	If async mode is enabled, fallback will be passed back when the flags have not yet been defined

Context

For advanced usage or building your own functionality, react-ld exposes it's underlying context so you can build your own utilities if necessary.

// Context structure
{
  async: boolean,
  flags: {
    [string]: boolean,
  },
}