Skip to content
Sign in
Lexy
Pricing Blog Lexy Originals About FAQ Help Center
Back to Help center

Control the quiz prompt from your own page

A developer guide to setting when the Overlay prompt shows, driving it from your own script and listening for its page events.

Widgets and embeds
Updated November 18, 2026

This guide is for developers. A widget in Overlay mode shows a small prompt that opens the quiz. Your page can set when and where that prompt shows on the widget's tag, show and hide it from your own script, open the quiz from your own button, and hear when the prompt appears.

Start by setting the widget's Widget Mode to Overlay. See Float a quiz over the page or the video.

Set it on the tag

Attributes on the widget's tag win over the settings saved with the widget, so one widget can behave differently on different templates.

<lexy-widget id="your-widget-id" appear="pause" dock="player"></lexy-widget>
<script src="https://cdn.lexy.fm/embed.js" async></script>
AttributeValuesWhat it does
appearready, now, watched, pause, end, manualWhen the prompt appears. The first five match the choices under When it appears. With manual, the prompt waits for your script to call show().
appear-afterSeconds, such as 45How long the viewer watches before the prompt appears, for appear="watched".
dockcorner, playerThe page corner, or on the video player.
positionblPuts the prompt at the bottom left. It sits at the bottom right to begin with.
appear valueThe prompt appears
readyWhen the reader has at least one question they can play
nowAs soon as the page has questions
watchedAfter the seconds in appear-after, or 30 seconds
pauseWhen the viewer pauses after watching at least five seconds, and when the video ends
endWhen the video ends, or when nearly all of it has been watched
manualWhen your script calls show()

Show, hide and open it from your script

The script adds LexyWidget.prompt to the page once it has loaded.

CallWhat it does
LexyWidget.prompt.show(id)Shows the prompt now, whatever the setting.
LexyWidget.prompt.hide(id)Hides the prompt until show(), or until the reader leaves the page.
LexyWidget.prompt.state(id)Returns { shown, why, ready, locked, total }.
LexyWidget.prompt.open(id)Opens the quiz, for a button of your own. It returns false when there is nothing to open, which is a page with no questions yet or a quiz the reader has finished.

The id is the one in the widget's tag. Leave it out and the call goes to every prompt on the page. A show() or hide() made before the widget has started is kept and applied when it starts.

Here is a pause screen of your own. Set appear="manual" on the tag, then show the prompt on pause and hide it on play.

var video = document.querySelector('video');
video.addEventListener('pause', function () {
  if (window.LexyWidget && LexyWidget.prompt) LexyWidget.prompt.show();
});
video.addEventListener('play', function () {
  if (window.LexyWidget && LexyWidget.prompt) LexyWidget.prompt.hide();
});

Hear when the prompt shows

The widget tells the page with two page events. Each is sent on the widget's tag and bubbles up to document.

Page eventWhen it happensWhat it carries
lexy:prompt_shownThe prompt appears.widgetId, why, ready, locked, total, lang
lexy:prompt_hiddenYour script hid the prompt, or the reader finished the quiz.widgetId, why, lang
FieldWhat it is
widgetIdThe widget's number, as on My Widgets.
whyOn lexy:prompt_shown, the reason it appeared, one of now, ready, watched, pause, end or manual. On lexy:prompt_hidden, manual or complete.
readyQuestions the reader can play now.
lockedQuestions still waiting to unlock.
totalQuestions in this reader's game.
langThe quiz's language.
document.addEventListener('lexy:prompt_shown', function (e) {
  console.log('Quiz prompt shown', e.detail.why, e.detail.ready);
});

The last lexy:prompt_shown detail stays on the widget's tag as lexyPrompt, for a script that starts listening late.

Open the quiz from your own button

lexy:questions_ready tells your page how many questions are ready each time the number changes, including while the prompt is waiting to appear. Use it to switch your own button on, then open the quiz with open().

<button id="quiz-button" hidden>Take the quiz</button>
<script>
  var button = document.getElementById('quiz-button');
  document.addEventListener('lexy:questions_ready', function (e) {
    button.hidden = e.detail.ready < 1;
  });
  button.addEventListener('click', function () {
    LexyWidget.prompt.open();
  });
</script>
  • With voice on, the quiz opens on a start screen. It shows the game's title and a Play the quiz button. The reader's tap on that button turns on sound and the microphone, and the quiz begins.
  • With voice off, the quiz begins at once.
  • Call it from the reader's tap. Over a fullscreen video the browser lets the quiz open only straight after a tap, so call open() inside your button's click handler.

What your page can see

Your page hears the counts, which are how many questions are ready, locked and in the game. The questions, the answers and the reader's progress stay inside the quiz, and each question opens only when the reader has reached its part of the story.

For game starts, answers and scores, see Track Lexy games in your own analytics.

Common questions

Does show() work before any question is ready?

Yes. The prompt shows, and its line says what unlocks the questions, such as 5 more unlock as you watch. The Start button opens the quiz once a question is ready.

Which id do I pass?

The id in the widget's tag, as copied from My Widgets. The widget's number works too.

Do the events also go to Google Tag Manager?

These two are page events only, like lexy:questions_ready. Game starts, answers and scores go to Tag Manager as well.