ShippingMethods container

The ShippingMethods container is designed to manage and display the selection of available shipping methods during the checkout process. You can configure it to handle the selection of shipping methods, display the available shipping methods, and manage the main slot for the shipping methods.

This container includes internal business logic to hide itself if the cart is empty or virtual.

Finally, if an error is thrown selecting a shipping method, a callback function is provided in order to handle that error in the integration layer; a rollback will be performed to the last valid shipping method selected by the user.

ShippingMethods configurations

The ShippingMethods container provides the following configuration options:

(*) Properties inherited from TitleProps

These configuration options are implementing the ShippingMethodsProps interface:

ShippingMethodsProps interface

The ShippingMethods container receives an object as a parameter which implements the ShippingMethodsProps interface with the following properties:

interface CartSyncError {
  method: ShippingMethod;
  error: Error;
}

export interface ShippingMethodsProps extends HTMLAttributes<HTMLDivElement>, TitleProps {
  active?: boolean;
  autoSync?: boolean;
  onCartSyncError?: (error: CartSyncError) => void;
  onSelectionChange?: (method: ShippingMethod) => void;
  UIComponentType?: UIComponentType;
}

• The displayTitle (*) property is inherited from the TitleProps interface. It is used to determine whether to display the title.
• Set the active property to true to have the container in reactive mode (it is visible and responds to system events). If it is set to false, the container is deactivated (it does not subscribe to system events and is not rendered).
• Set the autoSync property to true to automatically synchronize the container state changes with the backend via API calls. If it is set to false the container does not automatically synchronize its state, but still maintains local updates.
• The onCartSyncError property is a handler used to perform actions called when a shipping method is selected and the setShippingMethodsOnCart() API throws an error. It could be used in the integration layer by the merchant to show errors. -The onSelectionChange property is a handler used to perform actions called when a shipping method is selected.
• The UIComponentType property is a string containing the name of the UI component type to be used as a selector for each shipping method. The available UI components are: ToggleButton or RadioButton.
• The slots (*) property is inherited from the TitleProps interface. It is an object that contains the following properties:
  • Use the Title (*) property to render a custom title. This property is inherited from TitleProps interface.

Example

The following example renders the ShippingMethods container on a checkout page. It includes configurations to hide the title, show a message if the chosen shipping method is Best Way (Table Rate), and show an error message in case there was an issue saving the selected shipping method to the backend.

import ShippingMethods from '@dropins/storefront-checkout/containers/ShippingMethods.js';
import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';

const $delivery = checkoutFragment.querySelector('.checkout__delivery');

CheckoutProvider.render(ShippingMethods, {
  displayTitle: false,
  onCartSyncError: ({ method, error }) => {
    const shippingMsg = document.createElement('div');
    shippingMsg.style.color = 'red';
    shippingMsg.innerText = `Error selecting the Shipping Method ${method.code} for the carrier ${method.carrier.title}: ${error.message}`;
    $delivery.appendChild(shippingMsg);
  },
  onSelectionChange: (method) => {
    if (method.carrier.code === 'tablerate' && method.code === 'bestway') {
      const shippingMsg = document.createElement('div');
      shippingMsg.innerText = 'Shipping method not available for Canary Islands';
      $delivery.appendChild(shippingMsg);
    }
  },
})($delivery),