Note: The terms popup and lightbox refer to the same element. While the editor and dashboard now refer to it as a popup, the API methods continue to use the term lightbox for backward compatibility. The documentation uses both terms accordingly.
In this tutorial, we demonstrate how to create a popup that appears only on a visitor's first page load during a browser session. We'll create the popup element and use the Storage API to track whether a visitor has already seen the popup in their current session.
One-time popups are perfect for displaying important announcements, special offers, or welcome messages without repeatedly annoying visitors during their session.
We'll use the following steps to build the one-time popup:
Note: The code in this article was written using the following module versions:
Learn how to install npm packages in the editor or using the CLI.
It's important to note the following points before doing this tutorial:
In this step, you'll configure the popup element that will serve as the popup on your site.
To set up your popup:
In this step, you'll implement the code for tracking and displaying the popup.
Add the following import statements at the top of your masterPage.js file:
Note: Adding our code to the masterPage.js file ensures the popup appears immediately when a visitor first arrives at your site, regardless of which page they land on. To show the popup only on specific pages, add the code to those individual page files instead.
Add the main popup logic using the onReady() event handler.
When the page is ready, check session storage for firstTimePopupShown. If it's missing, open the "Announcement" popup and set the key so that the popup doesn't open again.
Note: This tutorial uses session storage, so the popup appears once per browsing session. To display the popup only once ever, use local storage instead. Change the import statement from session to local and update all instances of session to local in your code.