Event API

The Koral widget communicates through browser custom events dispatched on document.body. You can both fire events to trigger widget functionality and listen for events to react to user activity.

Activation Events

Use these events to control the widget programmatically.

koral_open

Opens the image search modal.

document.body.dispatchEvent(new CustomEvent('koral_open'));

---

koral_similar

Triggers a similar product search and opens the widget.

document.body.dispatchEvent(new CustomEvent('koral_similar', {
  detail: {
    productId: 'SKU-12345',      // Required
    imageUrl: 'https://...',      // Required
    filters: [{ key: 'brand', value: 'Nike' }],  // Optional
    type: 'similar',              // Optional
    context: {}                   // Optional
  }
}));

---

koral_similar_by_size

Triggers a similar product search with automatic size filtering.

document.body.dispatchEvent(new CustomEvent('koral_similar_by_size', {
  detail: {
    productId: 'SKU-12345',  // Required
    size: 'M',               // Required
    imageUrl: 'https://...'  // Optional
  }
}));

---

Programmatic API

In addition to custom events, the widget exposes a JavaScript API on the window object.

window.KoralModal

window.KoralModal.open()    // Opens the modal
window.KoralModal.close()   // Closes the modal
window.KoralModal.isOpen()  // Returns boolean

window.koralSimilarSearch(options)

window.koralSimilarSearch({
  productId: 'SKU-12345',
  imageUrl: 'https://...',
  filters: [],   // Optional
  type: '',      // Optional
  context: {}    // Optional
});

---

Output Events

Listen for these events on document.body to react to widget activity.

document.body.addEventListener('koral_product_click', (event) => {
  console.log('Product clicked:', event.detail.productId);
});

Event	Fired when
koral_close	Modal is closed
koral_product_click	User clicks a product (detail.productId)
koral_product_impression	Product becomes visible in viewport (detail.productId)
koral_similar_search	Similar search is performed
koral_image_upload	User uploads an image
koral_image_upload_search	Search is executed with uploaded image
koral_image_inspiration	User views inspiration gallery
koral_image_inspiration_category	User selects an inspiration category
koral_carousel_slide	Related products carousel is navigated

All events are dispatched on document.body.