OptimizelyProvider for the React SDK v4+

Wrap your React application at the root with OptimizelyProvider to give your entire React application access to Optimizely Feature Experimentation's APIs.

Minimum SDK version

v4.0.0+

For versions 3.x and earlier, see React SDK prior to v4.

Description

The OptimizelyProvider leverages React's Context API to provide the Optimizely client and user context to hooks like useDecide, useOptimizelyClient, and useOptimizelyUserContext.

Props

The following table lists the required and optional props for the OptimizelyProvider component:

Prop	Type	Required	Description
`client`	`Client`	Yes	Instance created from `createInstance`.
`user`	`{ id?: string; attributes?: UserAttributes } \| null`	No	User info object — `id` and `attributes` will be used to create the user context for all decisions and event tracking. Pass `null`, `undefined`, or omit while user info is being fetched — hooks will return `{ isLoading: true }` until a resolved user is provided. For VUID-only mode (no user ID), pass `user={{}}`.
`timeout`	`number`	No	Maximum time (in milliseconds) to wait for the SDK to become ready before hooks resolve with a loading state. Default: `30000`.
`qualifiedSegments`	`string[]`	No	Pre-fetched ODP audience segments for the user. Use `getQualifiedSegments` to obtain these segments server-side.
`skipSegments`	`boolean`	No	When `true`, skips background ODP segment fetching. Default: `false`.

📘
Note
If user information is not yet available, you can render <OptimizelyProvider> without it — hooks will return { isLoading: true } until a resolved user is provided. For VUID-only mode (no user ID), pass user={{}}. User Promise is not supported in v4.

Examples

If the root component of your application is <App>, wrap it with the OptimizelyProvider component. Pass the result of calling createInstance to the client prop and set the user object with id and attributes:

import React from 'react';
import {
  createInstance,
  createPollingProjectConfigManager,
  createBatchEventProcessor,
  OptimizelyProvider,
} from '@optimizely/react-sdk';

const optimizely = createInstance({
  projectConfigManager: createPollingProjectConfigManager({
    sdkKey: '<Your_SDK_Key>',
  }),
  eventProcessor: createBatchEventProcessor(),
});

function AppWrapper() {
  return (
    <OptimizelyProvider
      client={optimizely}
      user={{
        id: 'user123',
        attributes: {
          device: 'iPhone',
          lifetime: 24738388,
          is_logged_in: true,
        },
      }}
    >
      <App />
    </OptimizelyProvider>
  );
}

Async user loading

If user information must be fetched asynchronously, you can render the Provider immediately with user={null}. Hooks will return { isLoading: true } until a resolved user is provided:

import { useState, useEffect } from 'react';
import { OptimizelyProvider } from '@optimizely/react-sdk';
import { fetchUser } from './user';

function AppWrapper() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    fetchUser().then(setUser);
  }, []);

  return (
    <OptimizelyProvider client={optimizely} user={user}>
      <App />
    </OptimizelyProvider>
  );
}

VUID-only

For VUID-only mode (no user ID), pass an empty object as the user prop. The SDK uses an auto-generated visitor UID for decisions and event tracking:

import {
  createInstance,
  createPollingProjectConfigManager,
  createBatchEventProcessor,
  createOdpManager,
  createVuidManager,
  OptimizelyProvider,
} from '@optimizely/react-sdk';

const optimizely = createInstance({
  projectConfigManager: createPollingProjectConfigManager({
    sdkKey: '<Your_SDK_Key>',
  }),
  eventProcessor: createBatchEventProcessor(),
  odpManager: createOdpManager(),
  vuidManager: createVuidManager({
    enableVuid: true,
  }),
});

function App() {
  return (
    <OptimizelyProvider client={optimizely} user={{}}>
      <MyComponent />
    </OptimizelyProvider>
  );
}

Source files

The language/platform source files containing the implementation for React is index.ts.