Use Quiz API for Advanced Customization

The Quiz API lets your own JavaScript talk to a quiz while a visitor is filling it in. You can read what they answered, change a block, jump to a step, or submit, all without touching the quiz in the builder. You can use it anywhere JavaScript runs on the page: the quiz’s own custom code, a script block, or a tag manager snippet.

Get the API

The API is handed to you by the ll-quiz-init event as event.detail.llQuizApi. Keep that object and use it whenever you need it.

window.addEventListener('ll-quiz-init', (event) => {
  const quiz = event.detail.llQuizApi;

  quiz.getBlock('firstName').setValue('Ada');
});

Your script can run before or after the quiz loaded. If it registers late, ll-quiz-init is replayed to it automatically, so this pattern always works.

Every other quiz event carries the same llQuizApi, so you can also react to a step or an answer and act right there. See Quiz Events.

Steps and blocks by name

Every function that takes a step or a block accepts its name or its ID. Names are what you typed in the builder, so they are what you normally use. IDs are generated and look like block-3f9c….

quiz.getBlock('email'); // by name
quiz.getBlock('block-3f9c1a2e-…'); // by ID, same result
quiz.getBlocksByStep('contact');

Give every block and step a clear name in the builder. That is the only setup the API needs.

If two blocks or two steps share a name, the first one in quiz order is used.

Read the answers

getAnswers() returns every answer given so far, one entry per block. getAnswersSimple() returns the same answers as a simple object keyed by label. Hidden blocks and empty answers are left out.

quiz.getAnswers();
// [{ id: 'firstName', label: 'First name', value: 'Ada', key: 'firstName', stepId: 'step-…', stepName: 'contact' }, …]

quiz.getAnswersSimple();
// { 'First name': 'Ada', 'Plan': 'pro' }

These are exactly the fields and fieldsSimple the events carry, so code that handles one handles both.

Know where the visitor is

quiz.getCurrentStep(); // { id: 'step-…', name: 'contact', index: 1, total: 4 }
quiz.getCurrentStepBlocks(); // the blocks on that step
quiz.getSteps(); // [{ id, name, index }, …] in quiz order
quiz.getInfo(); // { quizId: 'quiz-…', isSubmitted: false }

index starts at 0. isSubmitted turns true once this visit submitted the quiz.

Find blocks

Call	Returns
`getBlocks()`	Every block that holds a value
`getBlock(nameOrId)`	One block
`getBlocksByStep(nameOrId)`	The blocks of one step
`getCurrentStepBlocks()`	The blocks of the step on screen

Lists only contain blocks that hold a value. Headlines, paragraphs, images and the like are never listed. getBlock() additionally finds buttons (Continue, Previous, Submit, Button), so you can change their text or disable them.

getBlock() never returns undefined. If nothing matches, or the block cannot hold a value, you get a placeholder block: every call on it logs a warning and does nothing, getValue() returns "". Your code never crashes, but check the console if something has no effect.

Which blocks hold a value?

Input fields (text, email, phone, number, textarea, date, birth date, zip code, address, OTP), choices (multiple choice, image choice, select), checkbox, range slider, upload, signature and hidden fields.Everything else is display or navigation: headline, paragraph, image, video, divider, list, loader, countdown, progress, accordion, links, custom code, tracking, and the buttons. Calling getValue(), setValue(), reset() or validate() on one of those throws an error. Containers are transparent: the blocks inside them are listed like any other block.

Read and change a block

Every block you get back is the same kind of object, so the examples below work on any block that supports the call.

Value

const name = quiz.getBlock('firstName');

name.getValue(); // 'Ada'
name.setValue('Grace');
name.reset(); // back to empty

Setting a value through the API triggers ll-quiz-value-change with source: 'api', so your listeners can tell it apart from the visitor typing.

Value formats by block

Checkbox: 'checked' or 'unchecked'
Multiple choice, image choice, select: the option’s value, for example 'pro'
Multiple choice with several selections: the values joined by the separator configured on the block
Everything else: the text the visitor typed

Label and placeholder

name.getLabel(); // 'First name'
name.setLabel('Given name');

name.getPlaceholder(); // 'Ada'
name.setPlaceholder('Type your first name');

quiz.getBlock('continue-1').setLabel('Next step'); // buttons too

Labels are plain text, except on a checkbox where HTML is allowed for links to terms. setLabel() and getLabel() throw on blocks that have no label.

Options

Multiple choice, image choice and select blocks expose their options:

quiz.getBlock('plan').getOptions();
// [{ id: 'option-…', label: 'Pro', value: 'pro', selected: true }, …]

Calling getOptions() on any other block throws.

Errors and focus

name.getErrors(); // ['This field is required.'] after a failed validation, [] otherwise
name.focus(); // move the cursor there

Buttons

const next = quiz.getBlock('continue-1');
next.disable();
await checkSomething(); // your own async work
next.enable();

enable() and disable() work on Continue, Submit and Button blocks and throw on anything else.

Visibility

const promo = quiz.getBlock('promoCode');

promo.visibility.hide();
promo.visibility.show();
promo.visibility.get(); // true, false or undefined (no override)
promo.visibility.clear(); // remove your override

A hidden block is not validated, not sent with the lead and not shown. undefined means you never changed it, so the block follows its own settings.

Validate

const step = await quiz.validateStep('contact'); // { success: false }
const block = await quiz.getBlock('email').validate(); // { success: false, errors: ['Invalid email address.'] }

Validation is asynchronous because email, phone and OTP fields are checked against a server. Hidden blocks always pass.

When a step fails, the quiz also fires ll-quiz-validation-error with every failing block and its message, marked source: 'api'. One listener can therefore handle both the visitor’s attempts and yours. Details on the events page.

Navigate and submit

await quiz.navigation.goNext();
quiz.navigation.goBack();
await quiz.navigation.goToStep('summary'); // name or ID
await quiz.navigation.submit();
quiz.navigation.goToUrl('https://example.com'); // add `true` to open a new tab

goNext(), goToStep() and submit() validate the step on screen first. If it is invalid they stay put, log a warning and fire ll-quiz-validation-error. goBack() never validates. submit() does exactly what the visitor’s Submit button does: the lead is saved, ll-quiz-submit fires with the server response, the single-submit protection applies, and the Submit button’s after-submit action runs. On a step without a Submit button the quiz submits and stays where it is. The returned promise resolves once all of that finished.

Recipes

Prefill from the URL

window.addEventListener('ll-quiz-init', (event) => {
  const quiz = event.detail.llQuizApi;
  const params = new URLSearchParams(window.location.search);

  if (params.get('email')) quiz.getBlock('email').setValue(params.get('email'));
  if (params.get('plan')) quiz.getBlock('plan').setValue(params.get('plan'));
});

Show a custom progress text

window.addEventListener('ll-quiz-step-view', (event) => {
  const { index, total } = event.detail.llQuizApi.getCurrentStep();
  document.querySelector('#progress').textContent = `Step ${index + 1} of ${total}`;
});

Jump to the first field with an error

window.addEventListener('ll-quiz-validation-error', (event) => {
  const { errors, llQuizApi } = event.detail;
  llQuizApi.getBlock(errors[0].blockId).focus();
});

Hold the Continue button until your own check passes

window.addEventListener('ll-quiz-step-view', async (event) => {
  const quiz = event.detail.llQuizApi;
  if (quiz.getCurrentStep().name !== 'eligibility') return;

  const next = quiz.getBlock('continue-eligibility');
  next.disable();
  const ok = await fetch('/api/eligible?zip=' + quiz.getBlock('zip').getValue()).then((r) => r.ok);
  if (ok) next.enable();
  else next.setLabel('Not available in your area');
});

Show a block only for one answer

window.addEventListener('ll-quiz-value-change', (event) => {
  const { blockName, value, llQuizApi } = event.detail;
  if (blockName !== 'plan') return;

  const promo = llQuizApi.getBlock('promoCode');
  value === 'premium' ? promo.visibility.show() : promo.visibility.hide();
});

Submit from your own button

window.addEventListener('ll-quiz-init', (event) => {
  const quiz = event.detail.llQuizApi;

  document.querySelector('#my-submit').addEventListener('click', async () => {
    await quiz.navigation.submit(); // validates first; resolves after ll-quiz-submit fired
    if (quiz.getInfo().isSubmitted) window.location.href = '/thank-you';
  });
});

Send the answers to your own endpoint

window.addEventListener('ll-quiz-submit', (event) => {
  fetch('https://example.com/leads', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(event.detail.fieldsSimple),
  });
});

All functions at a glance

Function	What it does
`getAnswers()` / `getAnswersSimple()`	Answers so far
`getCurrentStep()` / `getCurrentStepBlocks()`	The step on screen and its blocks
`getSteps()` / `getInfo()`	All steps; quiz id, submitted or not
`getBlocks()` / `getBlock()` / `getBlocksByStep()`	Find blocks
`validateStep(nameOrId)`	Validate a step
`navigation.goNext()` / `goBack()` / `goToStep()` / `submit()` / `goToUrl()`	Move and submit

On a block	What it does
`getValue()` / `setValue()` / `reset()`	The answer
`getLabel()` / `setLabel()` / `getPlaceholder()` / `setPlaceholder()`	Texts
`getOptions()`	Options of a choice or select block
`validate()` / `getErrors()` / `focus()`	Validation
`enable()` / `disable()`	Buttons
`visibility.show()` / `hide()` / `get()` / `clear()`	Show or hide
`blockID` / `blockType` / `variableName`	Identity

Older function names (still supported)

Earlier versions had one function per lookup type. They keep working exactly as before, so nothing you already wrote needs to change. New code should use the unified functions.

Older name	Use instead
`getBlockByID(id)` / `getBlockByName(name)`	`getBlock()`
`getBlocksByStepID(id)` / `getBlocksByStepName(name)`	`getBlocksByStep()`
`validateStepByID(id)` / `validateStepByName(name)`	`validateStep()`

Getting started

Landing Pages

Visual Editor (Canvas)

AI

Quizzes (Funnels)

Workflows

Lead Managment

Domain

Multi User

Testing and Reporting

Global Blocks

Integrations

Profile

Use Quiz API for Advanced Customization

Get the API

Steps and blocks by name

Read the answers

Know where the visitor is

Find blocks

Read and change a block

Value

Label and placeholder

Options

Errors and focus

Buttons

Visibility

Validate

Navigate and submit

Recipes

All functions at a glance

​Get the API

​Steps and blocks by name

​Read the answers

​Know where the visitor is

​Find blocks

​Read and change a block

​Value

​Label and placeholder

​Options

​Errors and focus

​Buttons

​Visibility

​Validate

​Navigate and submit

​Recipes

​All functions at a glance

Get the API

Steps and blocks by name

Read the answers

Know where the visitor is

Find blocks

Read and change a block

Value

Label and placeholder

Options

Errors and focus

Buttons

Visibility

Validate

Navigate and submit

Recipes

All functions at a glance