Optimizely will be sunsetting Full Stack Experimentation on July 29, 2024. See the recommended Feature Experimentation migration timeline and documentation.

Dev GuideAPI ReferenceUser Guide
Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySumbit a ticketLog In
GitHubNuGetDev CommunitySumbit a ticket

React hooks

This topic describes the React hooks that the Optimizely React SDK provides.

Suggest Edits

The React SDK provides the following React hooks:

useFeature hook

Retrieve the status of a feature flag and its variables. This can be useful as an alternative to the OptimizelyFeature component or to use feature flags & variables inside code that is not explicitly rendered.

Arguments

ArgumentTypeDescription
feature (required)StringThe feature flag key
options (optional)ObjectIncludes the following:
autoUpdate (boolean) - If true, this hook will update the feature flag and its variables in response to datafile or user changes. Default: false.
timeout (number) - Client timeout as described in the OptimizelyProvider section. Overrides any timeout set on the ancestor OptimizelyProvider.
overrides (optional)ObjectIncludes the following:
overrideUserId (string) - Override the userId for calls to isFeatureEnabled for this hook.
overrideAttributes (optimizely.UserAttributes) - Override the user attributes for calls to isFeatureEnabled for this hook.

Returns

Returns the following array:

KeyTypeDescription
isFeatureEnabledBooleanThe isFeatureEnabled value for the feature flag.
variablesVariableValuesObjectThe variable values for the feature flag.
clientReadyBooleanIndicates whether the ReactSDKClient instance is ready
didTimeoutBooleanIndicates whether the ReactSDKClient instance became ready within the allowed timeout range.

Note: clientReady can be true even if didTimeout is also true. This indicates that the client became ready after the timeout period.

Example

The following example shows using the useFeature hook to render something if a feature flag is enabled:

import { useEffect } from 'react';
import { useFeature } from '@optimizely/react-sdk';

function LoginComponent() {
  const [isEnabled, variables] = useFeature(
    'feature1',
    { autoUpdate: true },
    {
      /* (Optional) User overrides */
    }
  );
  useEffect(() => {
    document.title = isEnabled ? 'login1' : 'login2';
  }, [isEnabled]);

  return (
    <p>
      <a href={isEnabled ? '/login' : '/login2'}>{variables.loginText}</a>
    </p>
  );
}

useExperiment hook

Retrieves the variation key for an experiment, optionally auto updating the variation key based on underlying user or datafile changes. This can be useful as an alternative to the OptimizelyExperiment component or to use an experiment inside code that is not explicitly rendered.

📘

Note

The useExperiment hook causes a decision event and counts as an Impression.

Arguments

ArgumentTypeDescription
experiment (required)StringThe experiment key
options (optional)ObjectIncludes the following:
autoUpdate (boolean) - If true, this hook will update the experiment variation key in response to datafile or user changes. Default: false.
timeout (number) - Client timeout as described in the OptimizelyProvider section. Overrides any timeout set on the ancestor OptimizelyProvider.
overrides (optional)ObjectIncludes the following:
overrideUserId (string) - Override the userId for calls to isFeatureEnabled for this hook.
overrideAttributes (optimizely.UserAttributes) - Override the user attributes for calls to isFeatureEnabled for this hook.

Returns

Returns the following array:

KeyTypeDescription
variationStringReturns the variation key for the experiment
clientReadyBooleanIndicates whether the ReactSDKClient instance is ready
didTimeoutBooleanIndicates whether the ReactSDKClient instance became ready within the allowed timeout range.

Note: clientReady can be true even if didTimeout is also true. This indicates that the client became ready after the timeout period.

Example

The following example shows using the useExperiment hook to render something based on the returned experiment variation:

import { useEffect } from 'react';
import { useExperiment } from '@optimizely/react-sdk';

function LoginComponent() {
  const [variation, clientReady] = useExperiment(
    'experiment1',
    { autoUpdate: true },
    {
      /* (Optional) User overrides */
    }
  );
  useEffect(() => {
    document.title = variation === 'login1' ? 'login1' : 'login2';
  }, [variation]);

  return (
    <p>
      <a href={variation === 'login1' ? '/login1' : '/login2'}>Click to login</a>
    </p>
  );
}

Updated 8 months ago