Add to Cart Button#

When the Add to cart option is enabled in Templates and Design Options, a button appears on each product card in the widget. Clicking it does not add the product to the cart automatically — it fires a JavaScript event that your store needs to listen for and handle.

This design keeps SoloSearch decoupled from any specific ecommerce platform. Your store intercepts the event and calls whatever cart API or mechanism it already uses.

The event#

When the user clicks the Add to cart button, SoloSearch dispatches a custom DOM event on window:

solosearch:add-to-cart

The event's detail object contains the product data from the feed:

{
  id: "SKU-001",           // product ID from the feed
  title: "Running Shoes",
  price: 89.99,
  sale_price: 69.99,       // null if not on sale
  url: "https://myshop.com/running-shoes",
  image: "https://myshop.com/images/shoes.jpg",
  brand: "Nike",
  // ...any other fields indexed in the feed
}

The exact fields available depend on what is configured in your feed fields.

Listening for the event#

Add a JavaScript listener anywhere in your store's front-end code that runs after the page loads:

window.addEventListener('solosearch:add-to-cart', function (event) {
  const product = event.detail;

  console.log('Add to cart clicked:', product.id, product.title);

  // Call your store's cart API here
});

Confirming the operation#

While the add-to-cart operation is in progress, the widget shows a spinner on the button to indicate to the user that something is happening. Once your store has finished adding the product to the cart (whether successfully or not), you must dispatch a confirmation event back to SoloSearch so the spinner stops:

solosearch:add-to-cart-done

Dispatch it on window when the cart operation completes:

window.addEventListener('solosearch:add-to-cart', async function (event) {
  const product = event.detail;

  try {
    await myStore.addToCart(product.id, 1);
  } finally {
    window.dispatchEvent(new CustomEvent('solosearch:add-to-cart-done'));
  }
});

Using finally ensures the spinner always stops, even if the cart request fails.

Notes#

• Product ID mapping: the id field in the event detail is whatever your feed uses as the product identifier. Make sure this matches the ID expected by your platform's cart API. If they differ, you may need to use a different feed field (such as a custom cart_id field) and reference event.detail.cart_id instead.
• Quantities and variants: the event always passes a quantity of 1 and does not handle product variants. If your products have variants (sizes, colours), consider redirecting to the product page instead of adding directly to the cart.
• Confirmation feedback: after dispatching solosearch:add-to-cart-done, your store should update its mini-cart or show a notification so the user knows the action worked. SoloSearch stops the spinner but does not provide any further feedback on its own.