# JavaScript events

{% hint style="info" %}
This is an advanced customization. We recommend enlisting the help of a developer if you need assistance in implementing this functionality.
{% endhint %}

Custom JavaScript can be used to hook into existing theme functionality without touching theme code. This page serves as a reference for all the custom events Primavera exposes.

A custom event can be fired by instantiating an instance of the custom event, and then dispatching it.

```javascript
const event = new CustomEvent('dialog:trigger:cart-drawer');
document.dispatchEvent(event);
```

You can listen to an event listener by listening to it on the document element, just like any other event.

```javascript
document.addEventListener('dialog:open:cart-drawer', (event) => {});
```

### Dialog events

All the dialogs in the theme are triggered by the same set of core events.

You can open or close a dialog manually, or listen for existing open close events by replacing the \[name] text with the name of the dialog. The name of the dialog can be found in the data-name attribute. So for example, in the following snippet, the name is 'cart-drawer'.

```liquid
 <custom-dialog 
    data-modal="true" 
    data-overlay="true"
    data-name="cart-drawer" 
    data-section="{{ section.id }}"
    class="cart cart-drawer cart-drawer--{{ section.settings.layout_desktop }}">
```

This will open a modal. This can be useful if you need to manually open the cart drawer from another app or integration.

```javascript
new CustomEvent('dialog:trigger:[name]')
```

This listens for the open event of a modal. You might need to do this if you need to append something to a modals contents once it's open.&#x20;

```javascript
document.addEventListener('dialog:open:[name]', (event) => {
    // The target element is the DOM node of the modal
    console.log(event.detail.target)
});
```

&#x20;This will force a modal to close.

```javascript
new CustomEvent(`dialog:force-close:[name]`)
```

This listens for the close event. You might need to listen for this to do things like reset an animation.

```javascript
document.addEventListener('dialog:close:[name]', (event) => {
    // The target element is the DOM node of the modal
    console.log(event.detail.target)
});
```

### Quick add

This fires when the quick add is loaded. Maybe useful for appending or removing things to the quick add form dynamically.

```javascript
document.addEventListener(`dialog:quickadd-loaded`, this.onQuickAddLoaded.bind(this));
```

### Products

This event fires when a variant is changed.

```javascript
document.addEventListener('variant:change', (event) => {
  // The event detail includes the section id,
  // the full rendered HTML from the section rendering API, and the variant object
  const { sectionId, html, variant } = event.detail;
});
```

### Cart

This event fires when the shopping cart is updated.

```javascript
document.addEventListener('cart:change', (event) => {
  // The event detail includes the source of the change ('product-form' by default), 
  // the variant id, and the cart response as JSON. 
  const { source, productVariantId, cartData } = event.detail;
});
```

This event fires when there is a shopping cart error after an fetch event.

```javascript
document.addEventListener('cart:error', (event) => {
  // The event detail includes the source of the change ('product-form' by default), 
  // the variant id, the response.errors object and an optional message.
  const { source, productVariantId, errors, message } = event.detail;
});
```

{% hint style="info" %}
Need a custom event for your storefront that's not listed here? Just contact [our support](https://ultramarinastudios.com/support/) and let us know!
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ultramarinastudios.com/advanced/javascript-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.