less than a minute read • Updated 8 minutes ago
JavaScript events reference
The full list of Foxy JavaScript events available on the cart, checkout, and receipt, and how to bind, override, and trigger them.
Foxy’s JavaScript fires events for nearly everything that happens on the cart, checkout, and receipt. Bind to any of these with FC.client.on() to hook in your own custom behavior.
Binding to an event
FC.client.on('cart-submit', function (params, next) {
// your code here
});
Bind and unbind calls can be chained:
FC.client
.on('cart-item-remove', cartItemRemoveHandler)
.on('cart-item-remove.done', cartItemRemoveDoneHandler)
.on('cart-submit', cartSubmitHandler)
.on('cart-submit.done', cartSubmitDoneHandler);
FC.client
.off('cart-item-remove', cartItemRemoveHandler)
.off('cart-submit', cartSubmitHandler);
Every event listed below also fires a corresponding .done event once the action completes, for example cart-item-remove.done.
Available events
Template events
Event | Description | Params |
|---|---|---|
| Fires after a template block is updated. |
|
Sidecart events
Event | Description | Params |
|---|---|---|
| When the sidecart is displayed. |
|
| When the sidecart is hidden. | — |
| After the sidecart is hidden and detached from the DOM. | — |
Cart events
Event | Description | Params |
|---|---|---|
| When the cart is loaded — as an add to cart, view cart, empty cart request, etc. |
|
| When a quantity is changed in the cart. |
|
| When a product is removed from the cart. |
|
| When a coupon or gift card is added. |
|
| When a coupon is removed. |
|
| When a gift card is removed. |
|
| When the cart is updated, e.g. rendering Twig templates or setting | — |
| When shipping options are updated. |
|
Checkout events
Event | Description | Params |
|---|---|---|
| When the checkout is submitted. | — |
| When the checkout submit button is re-enabled after a stopped validation attempt. | — |
| When the checkout submit button is clicked, disabling it and triggering validation. | — |
| When shipping options are updated on the checkout. |
|
| When a customer initiates an express checkout option. |
|
| When a customer completes express checkout authentication. |
|
| When a customer cancels an express checkout option. |
|
| When an express checkout option errors. |
|
Customer events
Fired on both the cart and the checkout.
Event | Description | Params |
|---|---|---|
| When an entered email address is checked. |
|
| When a returning customer successfully logs in. | — |
| When a complete address is entered for an address type (e.g. billing/shipping). | — |
| When any customer address field is changed. |
|
| When a customer selects a shipping rate. | Parameters set to the contents of the address object (e.g. |
Analytics events
Fired on the cart, checkout, and receipt.
Event | Description | Params |
|---|---|---|
| Fires before adding an entry to the dataLayer for GTM integrations, allowing you to modify the data added for custom tracking. |
|
Usage examples
Pausing and canceling the event queue
Synchronous handlers can return false to stop processing:
FC.client.on('cart-item-remove', function (params) {
if (params.itemPrice == 0) {
alert('You cannot remove free products from your cart');
return false;
}
});
Declare a handler with a second parameter (conventionally next) to make it asynchronous. The event queue pauses until next() is called to continue, or next(false) to stop it. A returned value from an asynchronous handler is ignored:
FC.client.on('cart-coupon-add', function (params, next) {
$.ajax({
type: 'get',
url: 'http://api.example.com/check-coupon-availability',
dataType: 'jsonp',
data: { couponCode: params.couponCode }
}).done(function (data) {
if (data.ok) {
next();
} else {
alert('Sorry, your coupon is not available today.');
next(false);
}
});
}).on('cart-coupon-add.done', function (params) {
alert('Coupon ' + params.couponCode + ' has been added');
});
Getting an event
var event = FC.client.event('cart-item-remove');
Overriding the default action
FC.client.event('cart-item-remove').override(newDefaultHandler);
Creating and triggering a custom event
FC.client.wrap('your-own-event', function (params) {
// body
});
FC.client.event('your-own-event').trigger(params);
Validating a checkout field
This example requires a value on a date input inside a form with id="my-specific-form" before allowing the checkout to submit:
var FC = FC || {};
FC.onLoad = function () {
FC.client.on('cart-submit', function (params, next) {
$element = $(params.element);
if (
$element.attr('id') == 'my-specific-form'
&& $element.find('[name="date"]').length > 0
&& !$element.find('[name="date"]').val()
) {
alert('Date must be filled out');
} else {
next();
}
});
};
Preventing an add-to-cart with custom criteria
This example prevents adding a product from category Product2 if the cart already contains a product from category Product1:
FC.client.on('cart-submit', function (params, next) {
var product1_exists = false;
if (!jQuery.isEmptyObject(FC.json.items)) {
jQuery.each(FC.json.items, function (i, item) {
if (item.category == 'Product1') {
product1_exists = true;
}
});
}
if (params.data.category == 'Product2' && product1_exists) {
next(false);
} else {
next(true);
}
});
Notes
All events are accessed through
FC.client, which must be ready before binding — see JavaScript Overview for usingFC.onLoadto ensure this.Not every event has parameters — where none are listed above, the handler receives no arguments.
If you find an event you need that isn’t listed here, contact Foxy support.