Velo Tutorial: Creating a One-Time Popup

Visit the Velo by Wix website to onboard and continue learning.

In this article we demonstrate how to create a popup that appears the first time a visitor visits your site. We use a lightbox to create the popup and we use the wix-storage-frontend API to determine if the current visitor has already seen the popup.

We begin by adding a lightbox to the site. Note that when you add a lightbox, it appears in the Lightboxes section of your site pages.

We don't want the lightbox to show for site visitors unless we specifically open it using code. To make sure the lightbox doesn't open automatically, select the lightbox and click the Set Triggers button. Set the lightbox so that it does not automatically display on pages.

While the lightbox is still selected, click Set Triggers to set the Lightbox Settings. Here you can give your lightbox a meaningful name. In this example, we name our lightbox Announcement. The name will be used later in the code to open the lightbox.

Now you can design the lightbox to fit your needs. You can add, delete, and modify any of the elements that are contained in the lightbox. You can also change the layout and design of the lightbox.

Code

The code works using the following model. Each time a visitor visits your site we check the visitor's browser storage for a flag that we set the first time a visitor visits your site. If we don't find the flag, we know this is the visitor's first time visiting the site. So we show the popup and set the flag for the next time the visitor visits the site. If we find the flag, we know the visitor has visited the site already and we don't show the popup.

The following code is added to the Global Code section of the Code sidebar (Wix Studio), or to the masterPage.js file located in the Page Code section of the Velo sidebar (Wix Editor). Because the code is shared across all of your pages, it doesn't make a difference which page you are viewing when you add the code.

Imports

In this example we use the wix-storage-frontend API to store a value that tells us whether a visitor has seen the popup already. The wix-storage-frontend API uses the storage of a visitor's browser. We also use the wix-window-frontend API to open the lightbox that serves as our popup.

So our importing code looks like this:

Copy
1
import {session} from 'wix-storage-frontend';
2
import wixWindowFrontend from 'wix-window-frontend';

onReady( )

In the onReady() event handler, we check to see if the firstTimePopupShown key exists in the user's browser storage. The name of the key we check and set doesn't really matter. We just need to be consistent and make sure we check the same key that we set.

If the key doesn't exist, we open the lightbox using the lightbox's name. We also set a value for the firstTimePopupShown key so the key will be found the next time the user visits any of the site's pages.

So our onReady code looks like this:

Copy
1
$w.onReady(function () {
2
// flag is not found
3
if(!session.getItem("firstTimePopupShown")) {
4
// open popup
5
wixWindowFrontend.openLightbox("Announcement");
6
// set flag for future visits
7
session.setItem("firstTimePopupShown", "yes");
8
}
9
} );

If you've named your lightbox anything other than Announcement, you need to edit the code above to reflect your lightbox's name.

Customization

In this example, we've created a popup that appears the first time a visitor visits any page in your site during a single browsing session. With some minor adjustments, you can customize the example to behave in a different manner as described below.  

Session Storage vs. Local Storage

In this example, we used session storage to hold the flag that tells us if a visitor has seen the popup already. Session storage persists as long as the visitor's web session is active. The session ends when the visitor closes the browser tab or window. That means, using session storage, we show the popup the first time the visitor views the site for each individual session. If the visitor closes the browser tab and then visits the site again in a different tab, the popup will be shown again.

If you want to show the popup only once, regardless of whether a visitor is in the same browser tab or a new one, you can use local storage. Local storage never expires, even if a visitor closes your page. That means, using local storage, we show the popup the first time a visitor views the site. If a visitor closes the browser tab and then visits the site again in a different tab, the popup will not be shown again.

To change the code above so that it uses local storage instead of session storage, change all the instances of session to local.

That means the code should look like this:

Copy
1
import {local} from 'wix-storage-frontend';
2
import wixWindowFrontend from 'wix-window-frontend';
3
4
5
$w.onReady(function () {
6
if(!local.getItem("firstTimePopupShown")) {
7
wixWindowFrontend.openLightbox("Announcement");
8
local.setItem("firstTimePopupShown", "yes");
9
}
10
} );

Site vs Page

In this example, we placed our code in the Global Code section of the Code sidebar (Wix Studio), or the masterPage.js file in the Page code section of the Velo sidebar (Wix Editor). Code in masterPage.js runs on all the pages in a site. That means the popup will appear on the first page a visitor visits, regardless of which page it is.

If you want the popup to appear the first time a visitor visits a specific page, instead of any page on a site, move the code above into the page code for the page you want the popup to appear on.

API List

The following APIs are used in the code in this article. To learn more, see the API Reference.

Was this helpful?
Yes
No