Variation Code

A variation is one version of your experiment that a visitor can see: the original page (control) or a challenger. Each variation can have its own CSS and JavaScript. This page explains when that code runs and how the initVariation wrapper works. Following it helps you write variations that are reliable, fast, and safe to remove.

CSS injection

When a visitor is assigned to a variation, its CSS is injected first. A <style> tag containing all the variation's CSS rules is appended to the document's <head> element. This happens synchronously during experiment evaluation.

The page is still hidden by anti-flicker (a short delay that hides your page until the right variation is ready) at this point. Visitors never see the original version flash before it changes. See Anti-Flicker for the full detail.

Because the CSS lives in <head>, it applies to the whole page right away. Your CSS selectors style every matching element before the visitor ever sees the page.

/* This CSS is injected into <head> for visitors in this variation */.hero-title {  font-size: 3rem;  color: #1d4ed8;}.cta-button {  background-color: #22c55e;  border-radius: 9999px;  padding: 1rem 2rem;}

JavaScript injection: the initVariation wrapper

After CSS, the variation's JavaScript runs. Your code must be wrapped in a function named initVariation that receives a single options argument. This is exactly what a new variation starts with:

function initVariation(options: AvsbVariationOptions) {  // Apply your variation changes here. This runs once the experiment activates.  options.onRemove(function() {    // Undo anything you added. Timers/listeners/waitUntil started through    // options.* are cleaned up automatically.  });}

/** @type {(options: AvsbVariationOptions) => void} */function initVariation(options) {  // Apply your variation changes here. This runs once the experiment activates.  options.onRemove(function() {    // Undo anything you added. Timers/listeners/waitUntil started through    // options.* are cleaned up automatically.  });}

The snippet calls initVariation(options) automatically. The editor blocks saving if the wrapper function is missing or renamed.

When initVariation runs:

• The variation's CSS is already applied (CSS is injected first).
• The browser has almost always finished parsing the page's HTML by now. Before your code runs, A vs B already fetched the datafile (the small file listing every live experiment for your project). That trip takes real time. This is not a guarantee for every page, so still reach for options.utils.waitForElement (below) if you are not sure an element exists yet.
• The window.avsb global API is available.
• The page is still hidden by anti-flicker.

The options object

The options argument provides experiment context, lifecycle hooks, self-cleaning helpers, tracking utilities, and a recommendations client: everything your variation needs without reaching for global state.

Context properties

Lifecycle hooks

Self-cleaning helpers

These helpers work exactly like their native browser equivalents, but anything you start through them is automatically torn down when the variation is removed. You never need to cancel them manually.

Tracking utilities

Recommendations

options.recs is a ready-to-use recommendations client, pre-bound to the running experiment and variation. Calling options.recs.get({ recipe }) resolves items for a recipe and automatically attributes clicks and impressions to this variation, with no extra setup. See the Recommendations API reference for the full method list.

Basic example

A simple variation that changes a heading and reverts it when the variation is removed (for example, on SPA navigation). initVariation runs only once the variation is already being applied. So your DOM changes go directly in the function body: there is no separate activation step to wait for.

/** @type {(options: AvsbVariationOptions) => void} */function initVariation(options) {  // The function body IS the activation moment: apply changes directly  const heading = document.querySelector('.hero h1');  if (heading instanceof HTMLElement) {    heading.dataset.originalText = heading.textContent ?? '';    heading.textContent = 'The faster way to grow your business';  }  // Revert DOM changes when the variation is removed (e.g. on SPA navigation)  options.onRemove(() => {    const original = document.querySelector('.hero h1');    if (original instanceof HTMLElement && original.dataset.originalText) {      original.textContent = original.dataset.originalText;    }  });}

Tracking from a variation

Fire your own events when you need to be precise about what counts as a conversion, instead of relying only on click and pageview metrics:

/** @type {(options: AvsbVariationOptions) => void} */function initVariation(options) {  const upsellButton = document.querySelector('.accept-upsell');  if (upsellButton) {    options.addEventListener(upsellButton, 'click', () => {      // 'upsell_accepted' must match a metric's event key in this project      options.track.event('upsell_accepted');      options.track.purchase({        orderId: 'ord_' + Date.now(),        total: 19.99,        currency: 'USD',      });    });  }}

Waiting for dynamic content

On single-page applications, some elements are rendered by the JavaScript framework after the initial DOM parse. Use options.utils.waitForElement to delay your DOM work until the target element is ready: it resolves with the element itself. For a condition that is not an element, a global variable, a value from another script, use options.waitUntil instead. Both run through options, so both are cancelled automatically if the variation is torn down while waiting.

/** @type {(options: AvsbVariationOptions) => void} */function initVariation(options) {  // Give up after 5 seconds instead of the default 10  options.utils.waitForElement('#intercom-container', { timeout: 5000 }).then((container) => {    // Safe to modify: the widget is ready    container.classList.add('variant-position');    // Revert on removal    options.onRemove(() => {      const el = document.querySelector('#intercom-container');      if (el) el.classList.remove('variant-position');    });  });}

Accessing the DOM

Variation JavaScript normally runs after the DOM is parsed (see above). So you can usually use standard DOM APIs, like document.querySelector and document.getElementById, directly in the initVariation function body. You do not need to wait for a DOMContentLoaded event.

On single-page applications, elements rendered by the framework after the initial page load may not be present yet. Use triggers to delay activation until the element exists, or wait for it directly inside initVariation with options.utils.waitForElement.

If your code throws

A synchronous error in initVariation, one that throws before the function returns, is caught. A vs B reports it (see error capture) and it does not stop the rest of the page. Your code did stop at the point of the error though, so any changes you planned after that line never happen. Write defensive code anyway:

/** @type {(options: AvsbVariationOptions) => void} */function initVariation(options) {  // Good: check that the element exists before modifying it  const button = document.querySelector('.cta-button');  if (button) {    button.textContent = 'Start free trial';  }  // Bad: throws an error if .cta-button doesn't exist  // document.querySelector('.cta-button').textContent = 'Start free trial';}

An error inside a .then(), a timer, or an event handler, anything that runs after initVariation has already returned, is not caught by that same wrapper. Project JavaScript drops this kind of error silently. Variation code does not: every script A vs B injects carries a hidden marker naming its exact experiment and variation. So even a later, asynchronous error is traced back to the code that caused it.

Cleanup on SPA navigation

On single-page applications, when the visitor navigates away from a page where an experiment is running, A vs B automatically:

• Removes the <style> tag containing the variation's CSS.
• Cancels all timers, intervals, listeners, and waitUntil observers started via the options helpers.
• Runs any callbacks registered with options.onRemove.

Note that automatic teardown does not undo DOM text or attribute changes your code made: only the resources started through the options helpers are auto-cleaned. If your variation mutated the DOM directly, register an options.onRemove callback to reverse those changes.

Rotation and resize

Your variation's JavaScript runs once per page view. If a visitor rotates their device or resizes the browser window afterward, initVariation does not run again. Visual, no-code changes behave differently: they re-check the new width and switch to whatever matches, the same way they do on first load. See Responsive Edits for how that works.

If your variation's JavaScript needs to react when the window crosses a size boundary, for example to redo something only relevant on mobile, add your own window.matchMedia listener inside initVariation. That listener keeps working for as long as the variation is active, since it is ordinary code running in the page.

Editor linting

Variation code can be written in plain JavaScript or TypeScript, matching your experiment's language setting. When you save, the browser compiles what you wrote: TypeScript becomes plain JavaScript, and JavaScript passes through unchanged. It sends both your original source and the compiled result to A vs B. The compiled JavaScript, not your original TypeScript, is what runs in a visitor's browser.

The code editor has a linting control with three levels, the same three levels Project JavaScript uses:

• Off: no checking, no underlines.
• On (the default): the editor underlines type and syntax problems as you type. This is advisory; you can still save.
• Strict: turns on stricter TypeScript checks and blocks saving until you fix every reported error.

Linting is only available for TypeScript experiments, and it applies per experiment: each one carries its own separate setting.

Your project's shared types, declared once in shared.d.ts, are available here too, with no import needed. See Project JavaScript, Shared types for how to declare them.