BillToShippingAddress container

The BillToShippingAddress container includes a checkbox that allows users to indicate if the billing address is the same as the shipping address. If unchecked, the billing address form will be displayed.

This container provides internal business logic to hide itself in case the cart is empty or virtual.

BillToShippingAddress configurations

The BillToShippingAddress container provides the following configuration options:

These configuration options implement the BillToShippingAddressProps interface:

BillToShippingAddressProps interface

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

interface CartSyncError {
  error: Error;
}

export interface BillToShippingAddressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
  active?: boolean;
  autoSync?: boolean;
  onCartSyncError?: (error: CartSyncError) => void;
  onChange?: (checked: boolean) => void;
}

• 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 bill to shipping address checkbox is clicked and the setBillingAddressOnCart() API throws an error. It could be used as a callback in the integration layer by the merchant to show errors or perform other actions.
• The onChange property is a handler used to perform actions called when the checkbox is checked/unchecked.

Example

The following example renders the BillToShippingAddress container on a checkout page. It handles changes to the billing address form visibility and validation. If the billing address form is shown, it validates the form data and updates the billing address on the cart. Finally, an error message is shown in case there is an issue saving the billing address to the backend.

import * as checkoutApi from '@dropins/storefront-checkout/api.js';
import BillToShippingAddress from '@dropins/storefront-checkout/containers/BillToShippingAddress.js';
import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';

const DEBOUNCE_TIME = 1000;

const $billToShipping = checkoutFragment.querySelector(
  '.checkout__bill-to-shipping',
);
const $billingForm = checkoutFragment.querySelector(
  '.checkout__billing-form',
);

const billingFormRef = { current: null };

CheckoutProvider.render(BillToShippingAddress, {
  onCartSyncError: (error) => {
    const billToShippingMsg = document.createElement('div');
    billToShippingMsg.style.color = 'red';
    billToShippingMsg.innerText = `Error saving the Billing address with the Shipping address information: ${error.message}`;
    $billToShipping.appendChild(billToShippingMsg);
  },
  onChange: (checked) => {
    $billingForm.style.display = checked ? 'none' : 'block';
    if (!checked && billingFormRef?.current) {
      const { formData, isDataValid } = billingFormRef.current;

      setAddressOnCart({
        api: checkoutApi.setBillingAddress,
        debounceMs: DEBOUNCE_TIME,
        placeOrderBtn: placeOrder,
      })({ data: formData, isDataValid });
    }
  },
})($billToShipping),