Wait Until

waitUntil solves a common problem in A/B testing: what do you do when the element your variation needs does not exist in the DOM yet? Modern websites render content dynamically, and your variation code may run before that content is ready. waitUntil lets you safely wait for any CSS selector, JavaScript global, or custom condition to become available, then chains naturally with .then().

There are two forms: options.waitUntil (available inside trigger and variation code), which is automatically cancelled when the variation is torn down; and avsb.waitUntil (available anywhere on the page), which you can cancel manually via .stop(). Both share the same signature.

Signature

Both forms share the same overloaded signature. Pass a single target or an array of targets; receive a GuardedThenable you chain with .then():

1// Single target — resolves with the value the target returned
2waitUntil(target: WaitTarget, opts?: WaitOptions): GuardedThenable<unknown>
3
4// Multiple targets — resolves with an array of results (all must be ready)
5waitUntil(targets: WaitTarget[], opts?: WaitOptions): GuardedThenable<unknown[]>
6
7// A target can be any of:
8type WaitTarget =
9  | string        // CSS selector  e.g. ".hero-banner"
10  | string        // window path   e.g. "window.dataLayer"
11  | (() => unknown) // predicate  e.g. () => window.userProfile
12
13interface WaitOptions {
14  timeout?: number  // ms before the wait times out — default 10000
15  all?: boolean     // when true, selector resolves via querySelectorAll (array)
16}
17
18// GuardedThenable — like a Promise, but .catch() is OPTIONAL
19interface GuardedThenable<T> {
20  then(onFulfilled?, onRejected?): GuardedThenable<...>
21  catch(onRejected?):              GuardedThenable<...>
22  finally(onFinally?):             GuardedThenable<...>
23  stop(): void  // cancel the wait — thenable never settles after this
24}

Parameters

Return value

waitUntil returns a GuardedThenable — a promise-like object you can chain. Key differences from a native Promise:

• .catch() is optional. A rejected GuardedThenable logs the failure rather than raising an unhandled rejection.
• .stop() cancels the underlying wait engine. After stop() the thenable never settles, logs, or calls any chained handlers. Use this in teardown code.
• Chaining with .then() / .catch() / .finally() returns another GuardedThenable — the catch-optional guarantee applies to every link in the chain.

Target types

CSS selector

Pass a string that does not start with window. and it is treated as a CSS selector. The wait resolves once document.querySelector(selector) returns a non-null element, passing that element to .then().

1// Inside trigger / variation code — auto-cleaned on removal
2options.waitUntil('.hero-banner').then((banner) => {
3  banner.classList.add('variant-style');
4
5  options.onRemove(() => {
6    banner.classList.remove('variant-style');
7  });
8});

1options.waitUntil('.product-card', { all: true }).then((cards) => {
2  cards.forEach((card) => card.classList.add('highlighted'));
3});

Window global path

Pass a dot-separated string starting with window. (or a plain path like window.dataLayer) and the wait polls until that global is truthy, then resolves with its value.

1options.waitUntil('window.userProfile').then((profile) => {
2  if (profile.isPremium) {
3    const banner = document.querySelector('.upgrade-banner');
4    if (banner) banner.remove();
5  }
6});

Predicate function

Pass a function. It is called repeatedly until it returns a truthy value, which is then passed to .then(). The predicate should only read state — do not modify the DOM or trigger network requests inside it.

1options.waitUntil(() => window.Intercom && document.querySelector('#intercom-container'))
2  .then((container) => {
3    container.classList.add('variant-position');
4
5    options.onRemove(() => {
6      container.classList.remove('variant-position');
7    });
8  });

Multiple targets (array)

Pass an array of targets. The wait resolves once all targets are ready, passing an array of their resolved values to .then(). Each element can be a selector, window path, or predicate — they may be different types.

1options.waitUntil(['.checkout-form', 'window.cart', () => window.Stripe])
2  .then(([form, cart, stripe]) => {
3    // All three are guaranteed ready here
4    form.querySelector('.submit-btn').textContent = 'Complete Order';
5  });

Timeout behaviour

The default timeout is 10 000 ms (10 seconds). When the timeout expires the GuardedThenable rejects internally, but because.catch() is optional the failure is only logged — verbose in preview mode (so you see it in DevTools), silent for real visitors.

Pass a custom timeout in the options object:

1// Give up after 5 seconds
2options.waitUntil('.dynamic-widget', { timeout: 5000 }).then((el) => {
3  el.classList.add('variant');
4});

If the condition you are waiting for might never appear — for example, an element that only exists on certain pages — pass a reasonable timeout so polling does not run forever. For a wait you want to run indefinitely, pass timeout: 0 to disable the timeout entirely (use with caution).

Stopping a wait early

Call .stop() on the returned GuardedThenable to cancel the wait before it resolves:

1const wait = options.waitUntil('.checkout-form').then((form) => {
2  form.querySelector('.submit-btn').textContent = 'Complete Order';
3});
4
5// Cancel if the experiment decides to abort early
6someCondition && wait.stop();

When using options.waitUntil inside variation or trigger code, stop() is called automatically on variation removal and SPA navigation. You only need to call it manually when you want to cancel before that lifecycle event fires.

Migrating from the old callback API

The previous waitUntil API used a three-argument callback form that returned a { cancel } handle:

1// OLD — callback-based
2options.waitUntil(
3  () => document.querySelector('.hero'),
4  (el) => { el.classList.add('variant'); },
5  { timeout: 5000 }
6);

The new API is promise-based. Migrate by moving the callback into a .then() chain:

1// NEW — chain .then() on the target
2options.waitUntil('.hero', { timeout: 5000 }).then((el) => {
3  el.classList.add('variant');
4});

Key differences to keep in mind when migrating:

• The first argument is now the target (selector, window path, or predicate) — not a wrapper function. If you previously wrote () => document.querySelector('.x') as the condition, replace it with the selector string '.x' directly.
• The returned handle.cancel() is now .stop() on the GuardedThenable itself.
• No .catch() is required — failures log gracefully instead of throwing.