The vtex.shipping-option-components app is now deprecated and has been replaced by vtex.delivery-promise-components. We made this change to provide a more flexible and modular way to configure the Delivery Promise experience in your Store Framework storefront.
What has changed?
Previously, the Delivery Promise experience relied on the vtex.shipping-option-components app and a single header block, shipping-option-location-selector, to collect the shopper's location.
Now, the header experience is powered by the vtex.delivery-promise-components app, which provides three separate Store Framework blocks you can use:
shopper-location-setter(required): Collects the shopper's location data, such as postal code, to determine Delivery Promise availability and filters.shipping-method-selector(optional): Allows shoppers to choose between delivery and pickup after setting their location.pickup-point-selector(optional): Allows shoppers to choose a specific pickup point after setting their location.
Breaking changes for storefront themes
Migrating from vtex.shipping-option-components to vtex.delivery-promise-components requires more than just a dependency name change. The following table highlights the main breaking changes:
| Area | Before (vtex.shipping-option-components) | Now (vtex.delivery-promise-components) |
|---|---|---|
| Theme dependency | vtex.shipping-option-components | vtex.delivery-promise-components |
| Blocks | Single block: shipping-option-location-selector. | Separate blocks: shopper-location-setter, shipping-method-selector, and pickup-point-selector. |
| Block props | Props like callToAction, compactMode, and dismissible on one block. | Props are split across the new blocks, such as required, mode, and shippingSelection. |
| CSS handles | Handles such as buttonLabel, deliveryPopover, and shippingOptionButton. | New set of handles, including shopperLocationSetterContainer and shippingMethodSelector. Find the full updated list of CSS handles in the Delivery Promise Components app documentation. |
What needs to be done?
To adapt to this change and continue using Delivery Promise in your Store Framework storefront header, follow the instructions below:
- In your theme's
manifest.jsonfile, replace the dependencyvtex.shipping-option-componentswithvtex.delivery-promise-components:
-
Remove any usage of the
shipping-option-location-selectorblock from your header layout configuration. -
Add and configure the new blocks:
- Add the
shopper-location-setterblock to your header (Required). - Optionally, add the following blocks depending on your needs:
shipping-method-selectorto allow shoppers to choose between delivery and pickup.pickup-point-selectorto allow shoppers to choose a specific pickup point.
- Validate the storefront behavior by confirming that:
- The header collects the shopper's location.
- Delivery Promise availability and filters respond correctly to the chosen location, shipping method, and pickup point.
To learn more about configuring Delivery Promise in Store Framework, see the Setting up Delivery Promise components (Beta) guide and the Delivery Promise Components app documentation.