Hooks

The VWO FME React SDK provides a set of hooks to help you seamlessly integrate feature flagging, experimentation, and event tracking into your React application. These hooks provide an easy and flexible way to interact with the VWO SDK.

Here are the available hooks:

useVWOClient

useVWOClient is a custom React hook that provides access to the initialized VWO SDK client instance within components wrapped by VWOProvider. It enables interaction with the VWO platform for experiments, feature flags, and tracking.

Usage

The hook does not accept any parameters. It internally consumes the VWO context provided by VWOProvider.

const { vwoClient, isReady } = useVWOClient();

if (isReady) {
  // Using vwoClient, you can run experiments, track events, and manage feature flags.
  // For example, call methods like vwoClient.getFlag(), vwoClient.trackEvent(), etc.
}

Hook Lifecycle & Side Effects

• The hook internally accesses the VWO client and readiness state from the React context.
• If used outside of a VWOProvider, it logs an error and returns a default state with no client and isReady: false.
• If the context indicates the client is not ready, it returns a default state signaling the client is still initializing.
• The hook has No side effects (like state updates or async calls) happen inside this hook, it’s purely for safe retrieval of the VWO client from context.

Return Type

interface VWOClientResult {
  vwoClient: IVWOClient | null;
  isReady: boolean;
}

• vwoClient: The VWO SDK client instance if initialized; otherwise null.
• isReady: Boolean indicating whether the VWO client is fully initialized and ready for use.

Using the above vwoClientYou can call the different methods available directly without using any hooks.

Check if the feature flag is enabled using getFlag method:

const { vwoClient, isReady } = useVWOClient();

useEffect(() => {
  if (!isReady) return;

  (async () => {
    const userContext: IVWOContextModel = { id: 'user_123' };
    
    // Retrieve the flag using the feature key and userContext
    const feature: Flag = await vwoClient.getFlag('feature_key', userContext);
    // check if the flag is enabled
    const enabled = feature.isEnabled();
    // get specific variable value
    const variableValue = feature.getVariable('variable-key', 'default-value')
    // get all variables
    const allVariables = feature.getVariables();
  })();
}, [isReady]);

Track an event using trackEvent method.

const { vwoClient, isReady } = useVWOClient();
if (!isReady || !vwoClient) return;

const userContext: IVWOContextModel = { id: 'user_123' };
vwoClient.trackEvent('event_name', userContext);

If you want to check the status of trackEvent method, then you have to use await and store the result.

Set Attributes using setAttribute method:

const { vwoClient, isReady } = useVWOClient();
if (!isReady || !vwoClient) return;

const userContext: IVWOContextModel = { id: 'user_123' };
vwoClient.setAttribute('event_name', userContext);

useVWOContext

The useVWOContext hook is used to access the VWOContext, which provides shared context values for components that need to interact with the VWO SDK and user targeting information.

The useVWOContext hook provides access to setUserContext, which lets you dynamically update the user details. Updating the context this way triggers updates in all components consuming the VWO context, enabling real-time evaluation of feature flags based on the latest user data.

It should only be used within components wrapped by VWOProvider.

Usage

import React from 'react';
import { useVWOContext } from './VWOProvider';

const UpdateUserContextButton: React.FC = () => {
  const context = useVWOContext();
  // If you want to access the current user context, use - context.userContext
  
  const handleUpdateUser = () => {
    if (context && context.userContext && context.setUserContext) {
      // use setUserContext to update userContext 
      context.setUserContext({
        id: 'new-user-id',
        customVariables: {key: 'value'}
      });
    }
  };

  return (
    <div>
      <p>Click the button to update the user context:</p>
      <button onClick={handleUpdateUser}>Set User ID</button>
    </div>
  );
};

export default UpdateUserContextButton;

This hook does not accept any parameters.

Hook Lifecycle & Side Effects

• On component render, useContext(VWOContext) is called to retrieve context values.
• If the hook is used outside of a provider or the context is undefined, an error is logged and null is returned.
• If used correctly, it provides access to current context values and the updater function.
• There are no side effects inside this hook itself.
• Updating userContext via setUserContext may trigger re-renders in components using this hook.

📘

Important Considerations for setUserContext Usage

• Using setUserContext from the useVWOContext hook will cause any component using the useGetFlag hook to re-run its effect and likely re-render, since it depends on the userContext.
• Updating the id using setUserContext is treated as switching to a new user. This may result in different variation or flag values for the same feature. Additionally, it will be counted as a new visitor in VWO.

useGetFlag

useGetFlag is a custom React hook to fetch and manage the state of a specific feature flag from the VWO SDK. It allows components to retrieve the current status and variables of a feature flag based on a feature key and optional user context.

• Usage: Retrieve a feature flag using VWO client instance.
• More Info: Learn more about useGetFlag

useGetFlagVariable

useGetFlagVariable is a generic React hook that retrieves the value of a specific variable from a VWO feature flag. It provides a typed interface to safely access variables with a fallback default.

• Usage: Retrieve the value of a specific feature flag variable.
• More Info: Learn more about useGetFlagVariable

useGetFlagVariables

The useGetFlagVariable hook allows you to fetch all variables associated with a feature flag.

• Usage: Retrieve all feature flag variables.
• More Info: Learn more about useGetFlagVariables

useTrackEvent

The useTrackEvent hook allows you to track custom events within your app, such as user actions or conversions.

• Usage: Track important metrics, such as button clicks or completed purchases.
• More Info: Learn more about useTrackEvent

useSetAttribute

The useSetAttribute hook provides a simple way to associate these attributes with users in VWO for advanced segmentation.

• Usage: Assign user attributes to help with segmentation and personalization.
• More Info: Learn more about useSetAttribute