Custom HTML JavaScript API

Every Custom HTML block in Clarflow runs inside its own sandboxed frame with a built-in JavaScript library: window.Clarflow. It lets your custom code trigger native funnel functionality — advancing steps, reading and writing response variables, redirecting the host page, and adding products to a Shopify cart — without writing any postMessage plumbing yourself.

The SDK is injected automatically. No setup, no script tags — just call Clarflow.* from any <script> inside your Custom HTML block. It works everywhere your funnel renders: the editor preview, the hosted funnel page, and embedded funnels.

Quick start

A button that advances the funnel to the next step:

<button id="continue">Continue</button>
<script>
  document.getElementById('continue').addEventListener('click', function () {
    Clarflow.completeStep();
  });
</script>

Navigation

Clarflow.completeStep()

Marks this block's step as complete and advances the funnel to the next step (following your funnel's edges and any If/Else branching).

Clarflow.completeStep();

Clarflow.nextStep()

Alias of completeStep().

Clarflow.back()

Returns to the previous step (unwinds the visitor's step history).

Clarflow.back();

Clarflow.goToStep(position)

Jumps directly to an already-visited step by its 1-based position (the same number shown in the step counter). Forward jumps to steps the visitor hasn't reached yet are ignored — moving forward must go through completeStep() so required-field validation and If/Else branching still apply.

Clarflow.goToStep(2); // back to step 2

Clarflow.redirect(url)

Redirects the page hosting the funnel to a URL. In an embedded funnel this navigates the storefront page itself, not just the funnel frame. On a hosted funnel page (/p/...) it navigates that page directly.

Clarflow.redirect('https://yourstore.com/collections/recommended');

Response variables

Response variables are the values collected by your input, dropdown, and question elements (the same ones you can insert with {{variableName}} syntax). The SDK gives you live JavaScript access to them.

Clarflow.getVariable(name)

Returns the current value of a variable — a string, an array of strings (multi-select questions), or undefined if not set yet.

var goal = Clarflow.getVariable('fitness_goal');

Clarflow.getAllVariables()

Returns an object of all variable values collected so far.

var all = Clarflow.getAllVariables();
console.log(all); // { name: 'Sam', fitness_goal: 'strength', ... }

Clarflow.setVariable(name, value)

Sets a variable. Use this to store computed results (scores, recommendations) that later steps can display with {{name}} or use in If/Else conditions.

var score = answers.filter(function (a) { return a === 'yes'; }).length * 10;
Clarflow.setVariable('quiz_score', String(score));

Values should be strings (or arrays of strings) to behave consistently with {{variable}} interpolation and branching.

Clarflow.prefill(values)

Pre-fills a batch of answers by variable name. Unlike setVariable (which only sets the value used by {{tokens}}), prefill seeds the actual controls — text inputs, dropdown selections, and single/multi-select answers — as each step mounts, so the visitor sees them already filled in and required-field gating is satisfied.

Clarflow.prefill({
  email: 'user@example.com',   // seeds an email input
  plan: 'Pro',                 // selects the 'Pro' dropdown/MCQ option
});

Match keys to the variable names of your input, dropdown, and question elements. Values are the input text, or the option's display label for dropdowns and questions.

Listening for changes

Variables can change while your block is on screen (for example, an input element on the same step). Subscribe with Clarflow.on:

Clarflow.on('variables:change', function (values) {
  document.getElementById('greeting').textContent = 'Hi ' + (values.name || 'there');
});

Unsubscribe with Clarflow.off('variables:change', callback).

{{variable}} vs getVariable() — {{tokens}} are replaced once when the block renders. getVariable() and variables:change give you live values from JavaScript without re-rendering the block. Prefer the JS API when your script reacts to values; prefer {{tokens}} for static text.

Shopify cart

Clarflow.addToCart(options)

Adds a product to the Shopify cart of the page hosting your embedded funnel, then opens the theme's cart drawer/notification. Only works when the funnel is embedded in a Shopify store.

// By variant ID
Clarflow.addToCart({ variantId: 45678901234567, quantity: 1 });

// By product handle
Clarflow.addToCart({ handle: 'daily-multivitamin' });

On the storefront, Clarflow fires clarflow:add-to-cart:success / clarflow:add-to-cart:error DOM events on window after the cart request completes.

Layout

Clarflow.requestResize()

Custom HTML blocks auto-size to their content and re-measure on their own whenever the block grows or shrinks — expanding sections, collapsing panels and injected content are all handled for you. Call this only as an escape hatch, when you need the funnel to re-measure at an exact moment rather than on the next frame.

document.getElementById('details').hidden = false;
Clarflow.requestResize();

Events

Clarflow.on(event, callback) / Clarflow.off(event, callback)

Full example: computed recommendation

<div id="result">Calculating...</div>
<button id="shop" hidden>Shop my recommendation</button>

<script>
  var skin = Clarflow.getVariable('skin_type');
  var concern = Clarflow.getVariable('main_concern');

  var product = skin === 'dry' ? 'hydra-repair-cream' : 'clarifying-gel';
  Clarflow.setVariable('recommended_product', product);

  document.getElementById('result').textContent =
    'Based on your ' + skin + ' skin and ' + concern + ' concern, we recommend: ' + product;

  var btn = document.getElementById('shop');
  btn.hidden = false;
  btn.addEventListener('click', function () {
    Clarflow.addToCart({ handle: product });
    Clarflow.completeStep();
  });

  Clarflow.requestResize();
</script>

Versioning

Clarflow.version reports the SDK version (currently "2.0.0"). Every message the SDK sends also carries this version, so the funnel runtime can evolve the protocol without breaking older embeds.

console.log(Clarflow.version); // "2.0.0"

Notes & compatibility

• The SDK loads before your HTML, so Clarflow is always defined by the time your scripts run.
• Existing raw postMessage integrations (clarflow-step-complete, clarflow-add-to-cart) keep working — the SDK is additive.
• Each Custom HTML block gets its own isolated frame; blocks share data through response variables, not shared globals.
• addToCart and host-page redirect require the funnel to be embedded on a page running the Clarflow embed script (e.g. a Shopify store).
• Want to drive the funnel from the storefront page itself (outside a Custom HTML block)? See the Host Page JavaScript API — the same Clarflow.* surface, exposed by the embed script on the page hosting your funnel.