---
title: "React SDK"
description: "Install and configure the React SDK provider, and evaluate configs and feature flags in React components"
canonical_url: "https://docs.configdirector.com/sdks/browser/react"
---
# React SDK

> Install and configure the React SDK provider, and evaluate configs and feature flags in React components

<div hidden="true" dataTitleIcon="react-light">



</div>

<external-badges package-url="https://www.npmjs.com/package/@configdirector/react-web-sdk" registry="npm" repo="js-sdks/tree/main/packages/react-web-sdk">



</external-badges>

## Introduction

The React SDK is intended to be used by React web applications running on modern web browsers. All modern web browsers on popular platforms should be supported.

The minimum supported version of React is `16.8.0`.

Browser SDKs are tested on the latest versions of Chrome, Firefox, Safari, and Edge.

Telemetry collection within browser SDKs uses Web Workers to aggregate and send telemetry data. If the SDK runs on older browsers without Web Workers support, config evaluation will continue to work but no telemetry data will be collected for that session.

## Installation

The SDK can be installed from NPM: [https://www.npmjs.com/package/@configdirector/react-web-sdk](https://www.npmjs.com/package/@configdirector/react-web-sdk)

<code-group>

```bash [npm]
npm install --save @configdirector/react-web-sdk
```

```bash [yarn]
yarn add @configdirector/react-web-sdk
```

```bash [pnpm]Javascript
pnpm add @configdirector/react-web-sdk
```

```bash [bun]
bun add @configdirector/react-web-sdk
```

</code-group>

## Configure and initialize the provider

Initialize the provider with your client SDK key:

```tsx [main.tsx]
import { createRoot } from "react-dom/client"
import App from "./App"
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY">
    <App />
  </ConfigDirectorProvider>
);
```

Alternatively, you can initialize it with the HOC asynchronously and wait for initialization before starting your application. This can prevent the config values to flicker from the default value to the evaluated value during initialization.

An optional timeout can be provided to configure how long to await for the client to initialize before rendering the application. In the event of a timeout, the client will continue to attempt to connect in the background and config values will return the default value provided in code until a connection to ConfigDirector services is established.

```tsx [main.tsx]
import { createRoot } from "react-dom/client"
import App from "./App"
import { withProvider } from "@configdirector/react-web-sdk";

(async () => {
  const ConfigDirectorProvider = await withProvider({
    sdkKey: "YOUR-CLIENT-SDK-KEY",
    timeout: { 2_000 }, // 2,000 milliseconds timeout, defaults to 3,000
  });

  createRoot(document.getElementById('root')!).render(
    <ConfigDirectorProvider>
      <App />
    </ConfigDirectorProvider>
  );
})();
```

### Additional configuration options

These configuration options can be passed in to the `ConfigDirectorProvider` or to the `withProvider` HOC as an object in the second argument.

#### `context`

The context to be used during targeting rules evaluation:

```tsx [main.tsx]
import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider
    sdkKey="YOUR-CLIENT-SDK-KEY"
    context={{ id: "12345", name: "Example User", traits: { region: "North America" } }}>
    <App />
  </ConfigDirectorProvider>,
);
```

#### `logger`

By default, the SDK logs to the console and it is set to log warnings and errors only. You can configure a `logger` by either creating a ConfigDirector console logger with a different log level, or by implementing the `ConfigDirectorLogger` interface to provide your own logger. The interface can be used to create an adapter to another logging library.

Configure the ConfigDirector console logger to a different level:

```tsx [main.tsx]
import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider, createConsoleLogger } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY" logger={createConsoleLogger("debug")}>
    <App />
  </ConfigDirectorProvider>,
);
```

Implement your own logger adapter:

```tsx [main.tsx]
import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider, ConfigDirectorLogger } from "@configdirector/react-web-sdk";

const myLogger: ConfigDirectorLogger = {
  debug: function (message: string, ...args: any): void {
    // your specific logging library implementation here
  },
  info: function (message: string, ...args: any): void {
    // your specific logging library implementation here
  },
  warn: function (message: string, ...args: any): void {
    // your specific logging library implementation here
  },
  error: function (message: string, ...args: any): void {
    // your specific logging library implementation here
  },
};

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY" logger={myLogger}>
    <App />
  </ConfigDirectorProvider>,
);
```

#### `appName` and `appVersion`

These options allow you to provide your application's name and version. These values can be used in targeting rules conditionals. For example, if a certain feature should only be enabled starting with a certain version of your application.

```tsx [main.tsx]
import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY" appName="YOUR-APP-NAME" appVersion="1.0.2">
    <App />
  </ConfigDirectorProvider>,
);
```

#### `timeout`

The timeout, in milliseconds, to be used in initialization and when updating the context. This is how long the `withProvider` HOC will wait for data from ConfigDirector services before resolving its Promise. If the timeout is reached, `withProvider` will return but the client will still be in an unready status and returning default values. The client will continue to attempt to connect and retrieve config values in the background.

When using the `ConfigDirectorProvider`, the timeout is not as relevant since initialization will happen asynchronously.

```tsx [main.tsx]
import { createRoot } from "react-dom/client"
import App from "./App"
import { withProvider } from "@configdirector/react-web-sdk";

(async () => {
  const ConfigDirectorProvider = await withProvider({
    sdkKey: "YOUR-CLIENT-SDK-KEY",
    timeout: 2_000, // 2,000 milliseconds timeout, defaults to 3,000
  });

  createRoot(document.getElementById('root')!).render(
    <ConfigDirectorProvider>
      <App />
    </ConfigDirectorProvider>
  );
})();
```

#### `mode`

The connection mode, which can be `streaming`, `polling` or `offline`. It is recommended to use the default of `streaming` unless you have a specific need to use `polling` instead. Defaults to `streaming`.

Set `mode` to `offline` to run your application without connecting to ConfigDirector, for example in a suite of UI tests where each run pins every flag to a known value. An offline provider needs no `sdkKey`, opens no connection and sends nothing, so the application is invisible to the ConfigDirector dashboard: no evaluations are counted and no lifecycle state changes. Every context receives the same value and targeting rules are not applied.

Give the values in the `values` prop, with one value per config key. Your application decides where they come from, for example a module bundled with the test build:

```tsx [main.tsx]
import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider mode="offline" values={{ "new-checkout": true, "max-items": 20 }}>
    <App />
  </ConfigDirectorProvider>,
);
```

The config type of each value follows from the value itself: a boolean, an integral number (`integer`), any other number (`float`), a string, or an object or array (`json`). A value read with an in-code default value of another type returns the in-code default value, as it does against ConfigDirector. The status turns `ready` right after the provider mounts, and a new `context` keeps the same values. `values` can be given only in `offline` mode, and `pollingInterval`, `timeout` and `url` have no effect in it.

With `mode="offline"` and no `values`, the provider is ready at once and every config returns its in-code default value.

When the values cannot be loaded, because of a value such as `null` or because `values` is given in `streaming` or `polling` mode, the client never becomes ready: every config returns its in-code default value, the status stays `loading`, and the provider reports a `ConfigDirectorInitializationError` as an unhandled promise rejection. `withProvider` rejects with the same error.

If you come from LaunchDarkly, a map of values is what LaunchDarkly calls "flags from files", and `offline` with no values is its "offline mode".

#### `values`

The values to serve in `offline` mode, one value per config key. It can be given only in `offline` mode; see [`mode`](#mode).

#### `pollingInterval`

The interval, in seconds, between requests for config updates when `mode` is `polling`. It has no effect in `streaming` mode. A value below the minimum of 30 seconds is raised to 30 seconds and a warning is logged. Defaults to `60` seconds. See [Polling intervals](https://docs.configdirector.com/getting-started/architecture#polling-intervals).

```tsx [main.tsx]
import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY" mode="polling" pollingInterval={120}>
    <App />
  </ConfigDirectorProvider>,
);
```

#### `url`

The base URL used to connect to ConfigDirector services. This should only be provided if your environment requires you to configure a proxy server in order to connect to ConfigDirector services.

### Values kept on the device

By default, the client keeps the last values it received from ConfigDirector in the browser's `localStorage`, and serves them on the next launch of the same context until live values arrive. An application opened without a network, after at least one successful connection, shows the values ConfigDirector last sent instead of the default values provided in code. Every evaluation served this way reports the reason `cached`, with `isDefaultValue` set to `false`.

The client is not ready while it serves values kept on the device: the status stays `loading` until the provider's initialization completes with live values or its `timeout`, then `default`, and `ready` once live values arrive and replace them. The `cachedValuesLoaded` hook fires when the kept values are loaded, together with `configsUpdated` listing their keys, so watchers and hooks pick them up.

The values are kept for the context they were evaluated for, and served on the next launch only when the launch context has the same `kind` and `id`. A launch with another context serves the in-code default values until live values arrive, which then replace the kept values. A context without an `id` matches on the same site, as long as the site's data has not been cleared, because ConfigDirector derives its identifier from the instance ID the SDK stores; a context without an `id` keeps its percentage rollout bucket for as long as that instance ID lasts. Name, traits, app name and app version take no part in the match: live values correct them within a second when there is a network. Once the client is running, updating the context keeps serving the current values until the new context's values arrive, as it does with live values.

Turn it off, or supply your own store, with the `caching` prop, which takes the same object the [JavaScript SDK](https://docs.configdirector.com/sdks/browser/javascript#values-kept-on-the-device) takes:

- `enabled`
  - Whether to keep the last values received. With `false`, nothing is read or written, even when a `provider` is given.
  - Defaults to `true`
- `provider`
  - A store of your own, for example an encrypted one, implementing `CachingProvider`: `read()` returns the stored entry or `undefined`, `write(value)` replaces it, `remove()` deletes it, and `sizeLimit()` returns the largest entry, in bytes, the store accepts. Each of `read`, `write` and `remove` may return a promise. One provider instance serves one client.
  - Defaults to the browser's `localStorage`, under a key derived from the client SDK key, with a size limit of 256 KB

```tsx [main.tsx]
import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY" caching={{ enabled: false }}>
    <App />
  </ConfigDirectorProvider>,
);
```

The entry is one string whose format belongs to the SDK and may change between SDK versions; an entry a newer SDK cannot read is removed. Before every write the SDK measures the entry against `sizeLimit()`; above it, the entry is removed and a warning is logged once, so the device never serves values that no longer reflect the set. A provider that fails to read, write or remove is logged once and never stops the client: the worst outcome is the in-code default values. Keeping values on the device is ignored in `offline` mode.

The entry, and the `localStorage` key the SDK uses by default, carry a SHA-256 digest of the client SDK key, never the key itself. Browsers compute that digest only on pages served over `https` or from `localhost`, so on a plain `http` page on another host nothing is kept and a `provider` of your own is not called.

## Retrieve config values

Retrieve a config value with the `useConfigValue` hook:

```tsx [YourComponent.tsx]
import { useConfigValue } from "@configdirector/react-web-sdk";

function YourComponent() {
  const { value } = useConfigValue("my-config-key", false);

  return (<p>my-config-key: {value}</p>);
}

export default YourComponent;
```

You can also determine if the client is still initializing. This can be useful in the event of a slow connection where retrieving the initial config values may be slow, so rather than transition from the in-code default value to the evaluated value, you can show a loading state until the client is ready and config values are evaluated:

```tsx [YourComponent.tsx]
import { useConfigValue } from "@configdirector/react-web-sdk";

function YourComponent() {
  const { value, loading } = useConfigValue("my-config", "default value");

  if (loading) {
    return <p>Loading...</p>;
  } else {
    return <p>My config value: {value}</p>;
  }
}

export default YourComponent;
```

## Update the context

The browser connects with the context given to the provider's `context` prop. Give it there when you already know the context as the page loads, so the first connection carries it:

```tsx [main.tsx]
import { createRoot } from "react-dom/client"
import App from "./App"
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider
    sdkKey="YOUR-CLIENT-SDK-KEY"
    context={{ id: "12345", name: "Example User", traits: { region: "North America" } }}>
    <App />
  </ConfigDirectorProvider>
);
```

To change the context afterwards, for example when a user signs in, call `updateContext` from the `useContext` hook where the change happens. Each `updateContext` call opens a new connection with the new context:

```tsx [YourComponent.tsx]
import { useConfigValue, useContext } from "@configdirector/react-web-sdk";

function YourComponent() {
  const { value: myConfigValue } = useConfigValue("my-config", "default value");
  const { updateContext } = useContext();

  const onUpdate = async () => {
    await updateContext({
      id: "654321",
      name: "Another User",
      traits: {
        region: "Australia",
      },
    });
  };

  return (
    <div>
      <p>My config value: {myConfigValue}</p>
      <button type="button" onClick={onUpdate}>
        Update context
      </button>
    </div>
  );
}

export default YourComponent;
```

Rendering the provider with a different `context` prop updates the context the same way.

To evaluate configs for an entity other than a user, such as a tenant, set the context kind with `kind`:

```tsx [YourComponent.tsx]
updateContext({
  id: "acme",
  kind: "tenant",
  name: "Acme Inc.",
  traits: {
    plan: "enterprise",
  },
});
```

Leaving `kind` out means `user`. A context kind is 1 to 64 lowercase letters, digits, dashes, or underscores. A context with an invalid context kind is ignored: the SDK logs an error, and configs are evaluated as if no context had been given. Context kinds are available from version 1.7.0 of the SDK.

<note>

In client SDKs (browser and mobile), updating the context re-establishes a new connection to ConfigDirector servers with the new context. While the new connection is in flight, config values will continue to evaluate to the currently cached values from the prior context.

Give the provider the context you know when the page loads, so the first connection carries it. A context set only afterwards replaces a first connection that had none, and that first connection counts as a separate [monthly active user](https://docs.configdirector.com/getting-started/pricing-and-billing#billing-metrics).

</note>

The SDK keeps an instance ID in the browser's `localStorage` until the site's data is cleared, and ConfigDirector derives the identifier of a context without an `id` from it. A visitor who has not signed in keeps that identifier, and their percentage rollout bucket, from one visit to the next, and counts as one [monthly active user](https://docs.configdirector.com/getting-started/pricing-and-billing#billing-metrics) however often they visit.

## `useClient` hook

In the event that you need to have access to the underlying Javascript ConfigDirectorClient instance for more complex behaviors, you can access the instance via the `useClient` hook:

```tsx [YourComponent.tsx]
import { useClient } from "@configdirector/react-web-sdk";

function YourComponent() {
  const { client } = useClient();

  // Utilize the client for more involved logic

  return <p>A more complex component</p>;
}

export default YourComponent;
```

<warning>

Proceed with caution when using the `useClient` hook. The `useConfigValue` and `useContext` hooks manage listeners and cleanup automatically. However, if you make use of the `useClient` hook, you must manage cleaning up any listeners yourself.<br />


Additionally, any calls to `dispose`, `unwatch`, or `unwatchAll` on the client instance can have unintended side effects and may result in subtle bugs.

</warning>

### `evaluate`

The client's `evaluate(key, defaultValue)` reads a config the way `useConfigValue` does and returns the evaluation behind the value: the value, whether it is the in-code default value, the `reason`, the `valueId`, and the `variation`. The [JavaScript SDK](https://docs.configdirector.com/sdks/browser/javascript#evaluate) describes it. Use it where the reason matters at the point of the read, such as when reporting an evaluation to another system. It reads once and does not re-render the component when the value changes, so keep rendering with `useConfigValue`. The SDK exports the `ConfigEvaluation`, `EvaluationReason` and `Variation` types. `evaluate` is available from version 1.10.0, and its `variation` from version 1.11.0.

```tsx [CheckoutButton.tsx]
import { useClient } from "@configdirector/react-web-sdk";

function CheckoutButton() {
  const { client } = useClient();

  const startCheckout = () => {
    const evaluation = client.evaluate("new-checkout", false);
    analytics.track("checkout-started", { newCheckout: evaluation.value, reason: evaluation.reason });
  };

  return <button onClick={startCheckout}>Check out</button>;
}
```

### `track`

The client's `track(eventName, options)` reports to ConfigDirector that something happened for the current context, such as a completed checkout, so ConfigDirector can show it on the Live feed and count it for each variation of a running experiment. `options` is optional and takes a `value`, a number the event measures, and `details`, an object describing the event. An event counts for an experiment only when the current context has an `id`. The [JavaScript SDK](https://docs.configdirector.com/sdks/browser/javascript#track-events) describes the options and the limits. `track` is available from version 1.11.0.

```tsx [PayButton.tsx]
import { useClient } from "@configdirector/react-web-sdk";

function PayButton() {
  const { client } = useClient();

  const pay = async () => {
    const order = await submitOrder();
    client.track("checkout-completed", { value: order.total, details: { plan: order.plan } });
  };

  return <button onClick={pay}>Pay</button>;
}
```

## Test your components

Use the SDK's testing entry point, `@configdirector/react-web-sdk/testing`, to test components that read your configs and flags. It creates a **test client**: the SDK's real client connected to an in-memory server that your test controls. Only the connection to ConfigDirector is replaced. Everything else is the same code that runs in production, including `ConfigDirectorProvider` and the hooks, so your components behave exactly as they do against ConfigDirector, and no network connection is opened and no telemetry is sent.

Render the production `ConfigDirectorProvider` with its `client` prop:

```tsx [Checkout.test.tsx]
import { act, render, screen } from "@testing-library/react";
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";
import { createTestClient } from "@configdirector/react-web-sdk/testing";
import { Checkout } from "./Checkout";

test("shows the new checkout when the flag is on", async () => {
  const testClient = createTestClient({ values: { "new-checkout": true } });

  render(
    <ConfigDirectorProvider client={testClient.client}>
      <Checkout />
    </ConfigDirectorProvider>,
  );

  expect(await screen.findByText("New checkout")).toBeInTheDocument();

  act(() => testClient.setValue("new-checkout", false));
  expect(screen.getByText("Classic checkout")).toBeInTheDocument();
});
```

The provider renders its children before initialization completes, so the first assertion uses `findBy…` rather than `getBy…`. Wrap `setValue`, `removeValue`, and `replaceValues` in `act()`, since they re-render the components under the provider at once.

### Components that render their own provider

A component that contains the production provider, such as an `App` that renders `<ConfigDirectorProvider sdkKey="…">`, would build a real client. `installTestClient` makes every provider mounted without a `client` prop use the test client instead:

```tsx [App.test.tsx]
import { createTestClient, installTestClient } from "@configdirector/react-web-sdk/testing";

let testClient: TestClient;
let uninstallTestClient: () => void;

beforeEach(() => {
  testClient = createTestClient({ values: { "new-checkout": true } });
  uninstallTestClient = installTestClient(testClient);
});
afterEach(() => uninstallTestClient());

test("renders the app with the flag on", async () => {
  render(<App />);
  expect(await screen.findByText("New checkout")).toBeInTheDocument();
});
```

While installed, the provider's construction props (`sdkKey`, `url`, `mode`, `values`, `timeout`, `pollingInterval`, `logger`, `appName`, `appVersion`) are ignored; `context` and `hooks` apply to the installed client as they do with a `client` prop. `withProvider` also uses the installed client. A provider reads the installed client when it is constructed, so install before rendering. Installing again replaces the installed test client, and each uninstall function restores the one installed before it.

### What the provider does with a given client

- It never disposes a client it was given, whether through the `client` prop or `installTestClient`. It disposes only a client it built from its own props.
- It does not call `initialize` on a client that is ready or initializing. If the client is ready and the `context` prop is given and differs from the client's context, it calls `updateContext`. A provider given a ready client reports the `ready` status on its first render.
- `hooks` given with a `client` are registered on it while the provider is mounted and removed when it unmounts, like every other handler the provider registers.
- The `context` prop is compared by deep equality, on mount and on later renders, so a new object with the same contents does not reconnect.
- A `client` prop that changes after the provider mounted is ignored with a warning. Remount the provider, for example with a new `key`, to use another client.

### Test client controls

`values`, `setValue`, `removeValue`, and `replaceValues` take native values, and the config type follows from each value: a boolean, an integral number (`integer`), any other number (`float`), a string, or a plain object or array (`json`). `holdInitialization`, `completeInitialization`, and `failInitialization` drive `initialize`, so loading and error states can be tested, and `holdContextUpdate`, `completeContextUpdate`, and `failContextUpdate` do the same for `updateContext`. `contextUpdates` records the context of every `initialize` and `updateContext` call, and `trackedEvents` the events the code under test tracked with `track`. The [JavaScript SDK's testing section](https://docs.configdirector.com/sdks/browser/javascript#test-your-code) describes every control and what to expect from the client.


## Sitemap

See the full [sitemap](https://docs.configdirector.com/sitemap.md) for all pages.
