Skip to content

Event Listeners

Overview

Rebuy dispatches custom events throughout the lifecycle of its features, allowing you to hook into key moments and add custom functionality. All Rebuy events are dispatched on the document object using the browser's native CustomEvent API.

Key Concepts

  • Events fire on document — Use document.addEventListener() to listen
  • Data is in event.detail — Access event payload via the detail property
  • Events are synchronous — Handlers execute before Rebuy continues
  • Multiple listeners allowed — Add as many handlers as needed for the same event

Event Naming Conventions

Rebuy uses two naming patterns for events:

Pattern Example Used For
rebuy.eventName rebuy.loaded Core Rebuy lifecycle, Widget events
rebuy:module.eventName rebuy:cart.add Module-specific events (Cart, Smart Cart, etc.)

Both patterns work the same way

The naming difference is purely organizational. Both use document.addEventListener() and provide data via event.detail.

Listening for Events

The basic pattern for listening to any Rebuy event:

document.addEventListener('rebuy:cart.add', (event) => {
    // Access event data via event.detail
    const { cart, item } = event.detail;

    console.log('Item added:', item);
    console.log('Cart total:', cart.cart.total_price);
});

The event.detail Object

Every Rebuy event includes contextual data in event.detail. The structure varies by event type:

Event Type Common detail Properties
Widget events widget (widget instance), product or products
Cart events cart (Rebuy Cart module; access Shopify cart via cart.cart), item (line item)
Smart Cart events smartcart (Smart Cart instance), item
Landing Page events data (page data) 
// Example: Widget ready event
document.addEventListener('rebuy.ready', (event) => {
    const { widget } = event.detail;

    console.log('Widget ID:', widget.id);
    console.log('Products:', widget.data.products);
});

// Example: Cart change event
document.addEventListener('rebuy:cart.change', (event) => {
    const { cart } = event.detail;

    // cart is the Rebuy Cart module; cart.cart is the Shopify cart data
    console.log('Item count:', cart.cart.item_count);
    console.log('Total:', Rebuy.util.formatMoney(cart.cart.total_price));
});

Core Lifecycle Events

These events fire once during the Rebuy initialization process.

rebuy.beforeLoaded

Fires before Rebuy begins loading. Use this to configure settings or add early customizations.

document.addEventListener('rebuy.beforeLoaded', (event) => {
    console.log('Rebuy is about to load');

    // Configure Rebuy before it initializes
    window.RebuyConfig = window.RebuyConfig || {};
    window.RebuyConfig.customSetting = 'value';
});

rebuy.loaded

Fires when Rebuy has fully loaded and all features are initialized.

document.addEventListener('rebuy.loaded', (event) => {
    console.log('Rebuy is ready');

    // Safe to interact with Rebuy APIs
    console.log('Cart:', window.Rebuy.Cart.cart());
});

Event Reference by Feature

Rebuy provides events for each major feature. Click the links below for complete documentation:

Feature Documentation Key Events
Core This page rebuy.beforeLoaded, rebuy.loaded
Widgets Widget Event Listeners rebuy.init, rebuy.ready, rebuy.add, rebuy.show, rebuy.hide
Cart Cart Event Listeners rebuy:cart.ready, rebuy:cart.add, rebuy:cart.change
Smart Cart Smart Cart Event Listeners rebuy:smartcart.show, rebuy:smartcart.hide, line item events
Smart Search Smart Search Event Listeners Quick View events, Results Page events
Smart Collections Smart Collections Event Listeners rebuy:smartcollections.ready, product events
Bundle Builder Bundle Builder Event Listeners Bundle selection and cart events
Landing Pages Landing Pages Event Listeners Reorder and Reactivate page events

Common Patterns

Run Code After Rebuy Loads

document.addEventListener('rebuy.loaded', () => {
    // All Rebuy features are now available
    const cart = window.Rebuy.Cart.cart();

    if (cart.item_count > 0) {
        console.log('Customer has items in cart');
    }
});

Track Product Adds Across All Widgets

document.addEventListener('rebuy.add', (event) => {
    const { product, widget } = event.detail;

    // Send to analytics
    analytics.track('Product Added', {
        product_id: product.id,
        product_title: product.title,
        widget_id: widget.id,
        source: 'rebuy_widget'
    });
});

React to Cart Changes

document.addEventListener('rebuy:cart.change', (event) => {
    const { cart } = event.detail;

    // cart is the Rebuy Cart module; cart.cart is the Shopify cart data
    const shopifyCart = cart.cart;

    // Update custom UI elements
    document.querySelector('.custom-cart-count').textContent = shopifyCart.item_count;

    // Show free shipping progress
    const threshold = 5000; // $50.00 in cents
    const remaining = Math.max(0, threshold - shopifyCart.total_price);

    if (remaining === 0) {
        console.log('Free shipping unlocked!');
    }
});

Modify Widget Before Display

document.addEventListener('rebuy.beforeShow', (event) => {
    const { widget } = event.detail;

    // Add custom class based on product count
    const productCount = widget.data.products?.length || 0;

    if (productCount > 4) {
        widget.el.classList.add('rebuy-widget--large');
    }
});
See something that needs updating? Suggest an edit