Home > widget-integration > CartController

CartController class

Cart controller managing UI interactions, modal display, and cart operations

This controller provides extensive customization capabilities for Technical Support teams through protected extension points. All timing, selectors, translations, and behavior can be customized per-shop without modifying core code.

## Key Extension Points

### Button State Management - updateButtonState() - Customize button UI updates (text, disabled state, styling) - getButtonStateTranslations() - Override button text for different locales - getButtonSuccessResetDelay() - Control how long "Added!" shows (default: 500ms) - getButtonFailureResetDelay() - Control error state duration (default: 300ms)

### Cart Opening Behavior - shouldOpenCartAfterAdd() - Control when cart opens after add-to-cart - openCart() - Customize cart opening logic and animations - closeCart() - Customize cart closing and cleanup

### Theme Integration - getCartEnabledBodyClass() - Override body class for cart enabled state - getModalId() - Customize modal element ID - getModalOpenBodyClass() - Override body class when modal is open - getButtonTextSelectors() - Add custom theme button selectors

### Accessibility & Focus Management - setupWCAGAccessibility() - Extend WCAG compliance features - saveFocusElementBeforeCart() - Customize focus saving logic - restoreFocusAfterCart() - Customize focus restoration logic

## Common Customization Patterns

Signature:

export declare class CartController 

Example

// EXAMPLE 1: Multi-language shop with custom translations
window.boostWidgetIntegration.extend('CartController', (CartController) => {
  return class MultilingualCartController extends CartController {
    getButtonStateTranslations() {
      const locale = window.Shopify.locale || 'en';
      const translations = {
        de: {
          adding: 'Wird hinzugefügt...',
          added: 'Hinzugefügt!',
          failed: 'Fehler!',
          default: 'In den Warenkorb'
        },
        fr: {
          adding: 'Ajout...',
          added: 'Ajouté!',
          failed: 'Échec!',
          default: 'Ajouter au panier'
        }
      };
      return translations[locale] || super.getButtonStateTranslations();
    }
  };
});

// EXAMPLE 2: Premium shop with faster button feedback and custom styling
window.boostWidgetIntegration.extend('CartController', (CartController) => {
  return class PremiumCartController extends CartController {
    getButtonSuccessResetDelay() {
      return 300; // Faster than default 500ms
    }

    updateButtonState(button, state, customText) {
      super.updateButtonState(button, state, customText);

      // Add premium loading animation
      const icon = button.querySelector('.icon');
      if (state === 'adding') {
        icon?.classList.add('spinner-animate');
      } else {
        icon?.classList.remove('spinner-animate');
      }
    }
  };
});

// EXAMPLE 3: Shop that doesn't open cart for gift cards
window.boostWidgetIntegration.extend('CartController', (CartController) => {
  return class GiftCardCartController extends CartController {
    shouldOpenCartAfterAdd(params, result) {
      // Don't open cart for gift card purchases
      if (params?.productType === 'gift-card') {
        return false;
      }
      return super.shouldOpenCartAfterAdd(params, result);
    }
  };
});

// EXAMPLE 4: Shop with custom analytics tracking
window.boostWidgetIntegration.extend('CartController', (CartController) => {
  return class AnalyticsCartController extends CartController {
    async addToCart(params, button, shouldOpenCart, callback) {
      // Track before add
      this.trackAddToCartStart(params);

      try {
        const result = await super.addToCart(params, button, shouldOpenCart, callback);
        this.trackAddToCartSuccess(params);
        return result;
      } catch (error) {
        this.trackAddToCartFailure(params, error);
        throw error;
      }
    }

    trackAddToCartStart(params) {
      window.dataLayer?.push({
        event: 'add_to_cart_start',
        ecommerce: { items: [params] }
      });
    }

    trackAddToCartSuccess(params) {
      window.dataLayer?.push({
        event: 'add_to_cart',
        ecommerce: { items: [params] }
      });
    }

    trackAddToCartFailure(params, error) {
      window.dataLayer?.push({
        event: 'add_to_cart_error',
        error: error.message,
        params
      });
    }
  };
});

// EXAMPLE 5: Custom theme with different selectors
window.boostWidgetIntegration.extend('CartController', (CartController) => {
  return class CustomThemeCartController extends CartController {
    getButtonTextSelectors() {
      return [
        ...super.getButtonTextSelectors(),
        '.custom-theme-button',
        '.my-add-to-cart-btn'
      ];
    }

    getModalId() {
      return 'my-custom-cart-modal';
    }

    getCartEnabledBodyClass() {
      return 'custom-cart-enabled';
    }
  };
});

Constructors

Properties

Methods