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 buyer's location.
Now, the header experience is powered by the vtex.delivery-promise-components app, which provides three separate Store Framework blocks:
shopper-location-setter(required): Collects the buyer's location data, such as postal code, to determine Delivery Promise availability and filters.shipping-method-selector(optional): Allows buyers to choose between delivery and pickup options after setting their location.pickup-point-selector(optional): Allows buyers to select 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 changing the dependency name. 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 in one block. | Props 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. See 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 buyers to choose between delivery and pickup.pickup-point-selectorto allow buyers to select a specific pickup point.
- Add the
-
Validate the storefront behavior by confirming that:
- The header collects the buyer's location.
- Delivery Promise availability and filters respond correctly to the selected 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.