# Checkout as a Popup

The checkout popup feature allows customers to display the checkout page inside a modal dialog instead of redirecting customers away from the current page. When enabled, this creates a smoother, faster checkout experience and allows customers to complete their purchase without losing context.

## Enabling the Feature

The checkout popup becomes available when you include its template in your theme. No dashboard settings are required to activate it.

### How to Enable

To enable the checkout popup in your theme, include the following template:

```jinja
{% include "vitrin:checkout/checkout_dialog.jinja" %}
```

**Best Practice:**
It is recommended to use the checkout popup primarily on the Product Details Page (PDP), where the full product context (variants, quantity, options, etc.) is already available.

If you need to trigger the checkout popup from any other page, make sure you pass the exact same arguments required by the “Add Product” API, so the checkout receives the correct product data more on the add product api — [Please refer add product guide for theme developers.](https://docs.zid.sa/cart-1475306m0#add-product)

## Global API Objects

### `window.checkout_dialog`

Including the checkout popup template adds a global `checkout_dialog` object to the `window`. This object exposes the following methods:

### Methods

* **open()** – Opens the checkout popup.

* **close()** – Closes the checkout popup.

### Usage Examples

```javascript
// Open checkout popup from the cart page
window.checkout_dialog?.open();

// Close the popup
window.checkout_dialog?.close();
```
### Theme Usage Examples

`HTML`

```html
{% include 'vitrin:checkout/checkout_dialog.jinja' %}

<button type="button" onclick="zidProductBuyNow()">
    <img class="buy-now-progress d-none" src="{{ 'spinner.gif' | asset_url }}" width="25" height="25" />

    <span>{{ _("Buy now") }}</span>
</button>
```
`JS`
```javascript
window.zidProductBuyNow = async () => {

    const buyNowLoading = (isLoading) => {
         const buttonElement = $('.btn-buy-now');
         const loaderElement = $('.buy-now-progress');
         const iconElement = $('.buy-now-icon');

         buttonElement.prop('disabled', isLoading);
         loaderElement.toggleClass('d-none', !isLoading);
         iconElement.toggleClass('d-none', isLoading);
    };

    try {

        buyNowLoading(true);

        const response = await window.zid.cart.buyNow({ form_id:'product-form' },
        { showErrorNotification: true });

        buyNowLoading(false);

    } catch(error) {
        // Optional
        console.error(error)
    }

    buyNowLoading(false);

}
```

## Custom Styles Integration

The Checkout Popup supports the Zid Custom Styles system. You can override specific styles in a safe, isolated way without affecting other dialogs.

### How to Use Custom Styles

```javascript
window.zidCustomStyles = {
  checkout_dialog: {
    '.MuiDialog-paper': {
      borderRadius: '24px',
      backgroundColor: '#FFC9BF',
      maxWidth: '840px',
      boxShadow: '0 25px 50px rgba(0, 0, 0, 0.16)',
    },

    '.user-content': {
      borderRadius: '16px',
      padding: '14px 28px',
      fontWeight: '600',
    },

    '.guest-content': {
      fontSize: '22px',
      fontWeight: '700',
    },
  },
};
```

The component key for the checkout popup is **`checkout_dialog`**.

---

To understand the complete flow of the Custom Styles system — including structure, validation, and advanced usage — [please refer to the Custom Styles Guide for Theme Developers.](https://docs.zid.sa/custom-styles-guide-1702191m0)

---
## Best Practices

* Include the template **only where checkout can be triggered** (product page).
* Always use **optional chaining** when interacting with the API.
* Prefer popup-based checkout for better conversion rates and reduced navigation friction.
* If you need to run “Buy Now” or custom checkout flows, always pass a clear `source` identifier.

## API Reference Summary

| Method                              | Parameters           | Description                              |
| ----------------------------------- | -------------------- | ---------------------------------------- |
| `window.checkout_dialog.open()`     | none                 | Opens the checkout popup                 |
| `window.checkout_dialog.close()`    | none                 | Closes the checkout popup       		|


## Summary

* Enabled by including `{% include "vitrin:checkout/checkout_dialog.jinja" %}`
* Add only where checkout can be triggered in the product details page.
* Exposes `window.checkout_dialog` global object
* Supports custom flow types through `source`
* Optional chaining recommended
* Fully style-able through `window.zidCustomStyles.checkout_dialog`