VarianceExperiment React SDK

A lightweight, client-side React SDK for rendering A/B test variants and sending experiment impressions to analytics. Supports preview mode, shared caching, and works with and components.

---

Table of Contents

- Installation
- Usage
- Basic Example
- Preview Mode
- Hooks
- [useExperiment] (#useExperiment)
- API
- Props
- Methods

---

Installation

Install via pnpm:

``bash
pnpm add @varianceab/react-sdk
`

Or include via npm:

`bash
npm install @varianceab/react-sdk
`

Usage

$3

`tsx
import React from "react";
import { Experiment, Variant } from "@varianceab/react-sdk";

export default function App() {
return (




Welcome, visitor!

Try our new feature!

);
}
`

- The component fetches experiment data from the endpoint.
- The correct variant is rendered automatically.
- Analytics impressions are sent automatically.

$3

Preview mode allows rendering a specific variant without sending analytics events or fetching experiment data.

`tsx
import React from "react";
import { Experiment, Variant } from "@varianceab/react-sdk";

export default function Preview() {
return (
id="exp_1234"
clientId="client_123"
previewMode={true}
variantToPreview="var_456"
>



Unseen variant

Previewed variant

);
}
`

- previewMode={true} requires variantToPreview to be set.
- No network request is made in preview mode.
- No analytics impressions are sent.

Hooks

$3

The useExperiment hook allows you to access the currently active variant programmatically without wrapping your components in / JSX.

---

#### Parameters

`ts
useExperiment({
id: string; // Experiment ID
clientId: string; // Client ID
previewMode?: boolean; // Optional: render a specific variant without sending analytics
variantToPreview?: string; // Optional: the variant ID to preview when previewMode is true
})
`

#### Returns

`ts
{
variantId: string | null;
}
`

- variantId – The ID of the variant that was rendered.
- null if no variant is selected yet.

#### Example

`tsx
import React from "react";
import { useExperiment } from "@varianceab/react-sdk";

export default function MyComponent() {
const { variantId } = useExperiment({
id: "exp_1234",
clientId: "client_123",
previewMode: true,
variantToPreview: "var_456",
});

return (



);
}
`

- The hook internally mounts a hidden element to resolve the variant.
- You can use variantId to conditionally render components or trigger logic in your React app.
- Works in preview mode without sending analytics impressions.

#### Notes

- The hook does not send analytics events in preview mode.
- It updates after the microtask queue, so variantId is set asynchronously.
- Safe to use in any functional component.

API

$3

| Prop | Type | Description |
| ------------------ | ------- | ---------------------------------------------------------------- |
| id | string | The experiment ID. |
| clientId | string | The client ID for fetching experiments. |
| previewMode | boolean | If true, renders a specific variant for preview purposes. |
| variantToPreview | string | The variant ID to preview (required when previewMode` is true). |