About the Lightbox API

The Lightbox API lets you show the site's popups over the current page. The API calls a popup a lightbox, so its names, such as LightboxDefinition, use that word. Use it to open a popup from an action on the page, such as a product quick view, with the data the popup needs.

With the Lightbox API, you can:

• Open a popup over the current page.
• Specify a value when you open a popup, and read it from components inside the popup.
• Close the open popup.

Popups are pages. They appear in the pages map of @wix/site-service-pages alongside ordinary pages, with popup set to true.

Before you begin

It's important to note the following points before starting to code:

• Popups can't stack. Opening a popup closes any popup that's already open.
• The API doesn't report when a popup closes, and can't return data from a popup to the page that opened it. Site visitors can close a popup themselves at any time, so don't write code that waits for a popup to close or for a result from it.

Use cases

• Pass data to a popup when you open it
• Show the payload of the open popup

Terminology

• Popup: A page that opens over the page a visitor is already on, rather than replacing it.
• Lightbox: The API's name for a popup, as in LightboxDefinition and lightboxService.
• Payload: Data you pass to a popup when you open it, which components inside the popup can read.

SDK setup

To use the API, install the @wix/site-service-lightbox package:

Import the package

Import types

Import any type shown in these docs from @wix/site-service-lightbox/types:

Resolve the service

In a React component, resolve the service with the useService hook: