Pixlee Widget Events Guide

All widgets emit events when certain actions occur. You can optionally subscribe to these events using the 'subscribedEvents’ option in the JavaScript Widget. You might then send these to your own analytics provider as an example.

Subscribing to Widget Events

All widgets emit events when certain actions occur. You can optionally subscribe to these events using the 'subscribedEvents’ option, which accepts an array of strings. Currently the following events are available for subscription:

  • widgetLoaded: fired when a widget completes loading
  • photoOpened: fired when a user clicks on a photo, opening the lightbox
  • photoClosed: fired when a user closes a previously opened photo, closing the lightbox
  • photoChanged: fired when a user changes the currently opened photo
  • ctaClicked: fired when a user clicks on a photo’s call to action link within the lightbox
  • ctaChanged: fired when a user cycles through a photo’s call to action links within the lightbox
  • widgetNumPhotos: fired when the widget renders, contains photo count of gallery at load time
  • widgetLoadMore: fired when a user clicks on a photowall's "load more" button
  • widgetNavigated: fired when a user scrolls through any carousel style widget. note that this will NOT fire on backwards navigation, only forward.
  • uploaderOpened: fired when a user opens the photo uploader
  • uploadComplete: fired when a user succesfully completes the media upload process through Pixlee's uploader
  • atcComplete: fired when a user succesfully completes an add to cart using our "Direct Add to Cart" feature
  • socialShare: fired when a user initializes a share to social media from within the lightbox or directly from the widget (for css themes that support it)
  • widgetHidden: fired when a widget is hidden for A/B testing purposes

Passing the subscribedEvents option to Pixlee.addSimpleWidget/Pixlee.addProductWidget/Pixlee.addCategoryWidget will make the widget emit events for the selected actions. For example:

  widgetId: 12345,
  subscribedEvents: ['photoOpened', 'photoClosed’],

You can then add an event listener to your page in order to take actions when these events occur:

function receiveMessage(event) {
  // only listen to events coming from Pixlee
  if (!event.data) {
  try {
    const message = JSON.parse(event.data);

    switch(message.eventName) {
      case 'photoOpened':
        // take action when a photo is opened
      case 'photoClosed':
        // take action when a photo is closed
      case 'ctaClicked':
        // take action when a cta is clicked
      default: return;
  } catch (error) {
    // error during JSON.parse, skip
window.addEventListener("message", receiveMessage);

The following events contain additional information which can be accessed through the message.data property:

  • widgetLoaded: if you're using Pixlee's A/B test feature, then message.data exposes which bucket the user is in: { "abTest": true, "bucket": "B" }
  • widgetLoadMore: The height of the widget in pixels
  • widgetNumPhotos: The number of photos in the gallery on first load
  • atcComplete: a serialization of the product form
  • socialShare: an array of the serialized products assigned to the photo, and the social network being shared to
  • photoOpened: An object containing information about the photo including id, products, the visual index of the photo with respect to the rest of the gallery and more.
  • photoChanged: The id of the photo the user changed to
  • ctaClicked: Two fields describing the ctaText and ctaUrl of the call to action which was clicked
  • ctaChanged: The product/call to action's data fields with all associated information


Prepopulating email/username fields in uploader

  widgetId: 12345,
  subscribedEvents: ['uploaderOpened'],

function tryParse(str) {
  try {
    return JSON.parse(str);
  } catch(_) {}

window.addEventListener('message', (event) => {
  if (!event.data)
  const message = tryParse(event.data);
  if (!message)

  if (message.eventName === 'uploaderOpened') {
    // Can only set user profile in the uploader after the iframe for it has been opened
      email: localStorage.getItem('email'),
      name: localStorage.getItem('name'),