Hyvä JavaScript Events

Hyvä heavily uses events for decoupled components to communicate state changes across a page.

The Event/Subscriber pattern promotes the creation of decoupled and extensible components.

This list is not exhaustive, but covers the most commonly used events.

private-content-loaded

Unlike Luma, Hyvä loads all customer section data as a single structure. Once this data is available, the private-content-loaded event is dispatched.

All components requiring section data subscribe to this event.

You can subscribe using native JavaScript:

window.addEventListener('private-content-loaded', event => myFunc(event.detail.data));

or Alpine.js:

<div @private-content-loaded.window="prop=event.detail.data.sectionname" />

All section data is available in the event.detail.data object, with keys corresponding to section names.

reload-customer-section-data

Dispatch this event to manually reload customer section data. Hyvä does not automatically invalidate or reload sections like Luma.

While this might seem like a missing feature, it simplifies code and makes debugging easier.

window.dispatchEvent(new Event('reload-customer-section-data'));

To invalidate existing private content section data without immediate reloading, use:

const browserStorage = hyva.getBrowserStorage();
if (browserStorage) {
    browserStorage.removeItem('mage-cache-storage');
}

More information is available on the Working with sectionData page.

toggle-mobile-menu

On small devices, the top navigation menu overlays the full page.

Dispatch this event to toggle the mobile menu overlay on small devices. It has no visible effect on larger displays.

window.dispatchEvent(new Event('toggle-mobile-menu'));

toggle-authentication

This event triggers the Hyvä equivalent of the Luma authentication popup.

Its effect depends on whether the customer is logged in and if guest checkout is enabled:

• If guest checkout is allowed or the customer is logged in, this event redirects to the checkout page.
• Otherwise (if not logged in and guest checkout is disabled), it opens the authentication slider. Subsequent toggle-authentication events will not close an already open slider.

window.dispatchEvent(new Event('toggle-authentication'));

After a customer logs in via the authentication slider, they are redirected to the checkout page. You can provide an alternative redirect URL by setting detail.url:

window.dispatchEvent(new CustomEvent('toggle-authentication', {detail: {url: '/'}}));

toggle-cart

Dispatch this event to open the mini-cart. Once visible, subsequent toggle-cart events will not close it.

window.dispatchEvent(new Event('toggle-cart')); // open mini-cart drawer

Since Hyvä 1.3.0, you can close the mini-cart by adding {isOpen: false} to the payload:

window.dispatchEvent(new CustomEvent('toggle-cart', {detail: {isOpen: false}}));

clear-messages

Clears all splash messages rendered by the message component.

window.dispatchEvent(new Event('clear-messages'))

configurable-selection-changed

Dispatched on product detail pages when a configurable product option is selected. The event payload is:

{
  productId: (string) the configurable productId,
  optionId: (string) the newly selected optionId,
  value: (string) the newly selected option value,
  productIndex: (string) productId of the simple product used to display the image,
  selectedValues: (array) map of selected optionIds to option values,
  candidates: (array) productIds matching the current selection,
}

If candidates contains only one product ID, all required options are selected. Multiple candidates indicate an incomplete selection.

Observe this event to update page elements when a configurable product option is selected.

listing-configurable-selection-changed

Dispatched on product listing pages when a configurable product option is selected. The event payload is:

{
  productId: (string) the configurable productId,
  optionId: (string) the newly selected optionId,
  value: (string) the newly selected option value,
  productIndex: (string) productId of the simple product used to display the image,
  selectedValues: (array) map of selected optionIds to option values,
  candidates: (array) productIds matching the current selection,
}

If candidates contains only one product ID, all required options are selected. Multiple candidates indicate an incomplete selection.

Observe this event to update page elements when a configurable product option is selected.

update-product-final-price

This event is only relevant on product detail pages.

It is dispatched when a visitor selects product options that influence the product price.

The product options component observes this event to recalculate price changes. Other components needing the current final price can also observe it.

<input @update-product-final-price.window="recalculateWithFinalPrice(event.detail)">

update-prices-getId() ?>

This event is relevant on product detail and listing pages.

It is dispatched when a visitor selects product options that change the associated simple product, updating the product's price accordingly.

On product detail pages, prices are given using oldPrice and finalPrice (including tax) or baseOldPrice and basePrice (excluding tax).

On product listing pages (e.g., categories), the keys are always finalPrice and oldPrice.

For example:

window.dispatchEvent(
  new CustomEvent(
    'update-prices-68', 
    {
      detail: {
        tierPrices: [],
        basePrice: {amount: 5},
        baseOldPrice: {amount: 15}
      }
    }
  )
)

On a product detail page for product ID 68, this will update the displayed price to 5 in the current currency.

Note: If no tier prices are set, the tierPrices key must still be an empty array in the event payload, as shown above.

More information on product price logic can be found on the PDP price logic page.

update-qty-getId() ?>

This event is only relevant on product detail pages.

Dispatched when the quantity for the add-to-cart input changes. The new quantity is passed in event.detail.

The product detail page observes this event to recalculate the product's final price. Components needing the quantity value can also observe it:

const eventName = 'update-qty-<?= (int)$product->getId() ?>';
window.addEventListener(eventName, event => this.currentQty = event.detail);

update-gallery

This event is only relevant on product detail pages. It is dispatched to update the product gallery images.

The event.detail payload is an array of image objects with the following structure:

{
    thumb: "https://...small image url",
    img: "https://...medium image url",
    full: "https://...large image url",
    caption: "the image label",
    position: 1,
    isMain: false,
    type: "image",    // or 'video',
    videoUrl: null    // or 'https://…youtube or vimeo video url'
}

Components can dispatch the update-gallery event to change visible product images or observe it to react to image changes.

To revert the gallery to its initial state, dispatch the event with an empty images array:

window.dispatchEvent(new CustomEvent('update-gallery', {detail: []}));