Documentation
Feedback
Guides
VTEX IO Apps

VTEX IO Apps
Advanced components
Product Comparison
Official extension
Version: 0.19.1
Latest version: 0.19.1

{"base64":"  ","img":{"width":110,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://img.shields.io/badge/all_contributors-0-orange.svg?style=flat-square"}}

The Product Comparison app compares specifications of pre-selected SKUs, allowing customers to better understand their needs when shopping.

The app exports several blocks, which you can leverage to display a Product Comparison drawer on your store's search results page and a new Product Comparison page.

{"base64":"  ","img":{"width":1886,"height":843,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":451727,"url":"https://user-images.githubusercontent.com/2637457/90900569-43a41a00-e3e7-11ea-9aa9-9a12bbec8c5e.png"}}

Product Comparison drawer on the store's search results page

{"base64":"  ","img":{"width":1456,"height":937,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":270488,"url":"https://user-images.githubusercontent.com/2637457/90900828-a1386680-e3e7-11ea-96d1-e9ba2022aa7d.png"}}

Product Comparison page

Configuration

Step 1 - Adding the Product Comparison app to your theme's dependencies

In your theme's manifest.json file, add the Product Comparison app as a dependency:


_10
"dependencies": {
_10
+ "vtex.product-comparison": "0.x"
_10
}

Now, you can use all the blocks exported by the Product Comparison app. Check out the full list below:

Block nameDescription
product-comparison-drawer
{"base64":"  ","img":{"width":69,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://img.shields.io/badge/-Mandatory-red"}}
Main block that renders the drawer from the Product Comparison component in which the items will be compared.
list-context.comparison-product-summary-sliderExtends the list-context block to build the Product Comparison component using the Slider Layout
product-summary.shelf.product-comparisonExtends the default product-summary.shelf block (from the Product Summary app) for the Product Comparison component's features.
product-comparison-blockLogical block that, once extended (see blocks listed below), renders the Product Comparison component's features.
product-comparison-block.selectorRenders the selector checkbox on the Product Comparison component.
product-comparison-block.close-buttonRenders the close button on the Product Comparison component.
product-comparison-block.product-summary-rowRenders the first row to list and compare products on the Product Comparison component.
list-context.comparison-rowExtends the list-context block to build a row in the Product Comparison page using the Slider Layout
product-comparison-block.grouped-product-specificationsRenders the section for product specification groups.
product-comparison-block.product-specificationsRenders the section for product specifications.
product-comparison-block.sku-specificationsRenders the section for SKU specifications.

Step 2 - Adding extended interfaces

In the theme's interfaces.json file, add the following extended interfaces:


_12
+{
_12
+ "store.search.product-comparison": {
_12
+ "around": ["comparison-context-wrapper"]
_12
+ },
_12
+ "search-result-layout.desktop.product-comparison": {
_12
+ "allowed": ["product-comparison-drawer"]
_12
+ },
_12
"store.product.product-comparison": {
_12
"around": ["comparison-context-wrapper"],
_12
"allowed": ["product-comparison-drawer"]
_12
}
_12
+}

Step 3 - Wrapping the search blocks with Product Comparison context

  1. In the theme's search.jsonc file, replace the default store.search blocks with the store.search.product-comparison blocks, as shown in the example below:

_23
{
_23
...
_23
- "store.search": {
_23
+ "store.search.product-comparison": {
_23
...
_23
},
_23
- "store.search#brand": {
_23
+ "store.search.product-comparison#brand": {
_23
...
_23
},
_23
- "store.search#department": {
_23
+ "store.search.product-comparison#department": {
_23
...
_23
}
_23
- "store.search#category": {
_23
+ "store.search.product-comparison#category": {
_23
...
_23
}
_23
- "store.search#subcategory": {
_23
+ "store.search.product-comparison#subcategory": {
_23
...
_23
}
_23
...

The store.search.product-comparison blocks wrap the store.search block with comparison context. The replacement is needed to synchronously display the selected products in the Product Comparison drawer.

  1. Replace the search-result-layout.desktop blocks with the search-result-layout.desktop.product-comparison blocks, as shown below:

_10
{
_10
...
_10
"search-result-layout": {
_10
"blocks": [
_10
- "search-result-layout.desktop#search"
_10
+ "search-result-layout.desktop.product-comparison#search",
_10
"search-result-layout.mobile",
_10
"search-not-found-layout"
_10
]
_10
},

  1. Replace the product-summary.shelf, child of the gallery block, with the product-summary.shelf.product-comparison:

_10
"gallery": {
_10
- "blocks": ["product-summary.shelf"]
_10
+ "blocks": ["product-summary.shelf.product-comparison#search"]
_10
}
_10
...

Step 4 - Adding the Product Comparison to the product detail Page

  1. In the theme's product.json file, replace the default store.product blocks with the store.product.product-comparison blocks, as shown in the example below:

_10
_10
- "store.product": {
_10
+ "store.product.product-comparison": {
_10
...
_10
}

  1. Add product-comparison-drawer to the store.product.product-comparison children, as shown in the example below:

_10
"store.product.product-comparison": {
_10
children:[
_10
...
_10
+ "product-comparison-drawer"
_10
]
_10
...
_10
}

  1. Add product-comparison-block.selector#pdp to the store.product.product-comparison block, as shown in the example below:

_10
"store.product.product-comparison": {
_10
...
_10
children:[
_10
...
_10
+ "product-comparison-block.selector#pdp"
_10
]
_10
...
_10
}

Step 5 - Building the Product Comparison component

In any desired template, such as store.search, add the product-comparison-drawer block, as shown below:


_21
- "search-result-layout.desktop#search": {
_21
+ "search-result-layout.desktop.product-comparison#search": {
_21
"children": [
_21
"flex-layout.row#did-you-mean",
_21
"flex-layout.row#suggestion",
_21
"flex-layout.row#banner-one",
_21
"flex-layout.row#searchbread",
_21
"flex-layout.row#searchtitle",
_21
"flex-layout.row#result",
_21
+ "product-comparison-drawer"
_21
],
_21
"props": {
_21
"pagination": "show-more",
_21
"preventRouteChange": false,
_21
"mobileLayout": {
_21
"mode1": "small",
_21
"mode2": "normal"
_21
}
_21
}
_21
}
_21
...

By adding the product-comparison-drawer block as shown above, you will declare the following structure behind the scenes:


_44
"product-comparison-drawer": {
_44
"blocks": ["list-context.comparison-product-summary-slider#drawer"]
_44
},
_44
"list-context.comparison-product-summary-slider#drawer": {
_44
"blocks": ["product-summary.shelf.product-comparison#drawer"],
_44
"children": ["slider-layout#comparison-drawer"]
_44
},
_44
"slider-layout#comparison-drawer": {
_44
"props": {
_44
"blockClass": "comparison-drawer",
_44
"itemsPerPage": {
_44
"desktop": 4,
_44
"tablet": 3,
_44
"phone": 1
_44
},
_44
"showPaginationDots": "never",
_44
"infinite": true,
_44
"fullWidth": true
_44
}
_44
},
_44
"product-summary.shelf.product-comparison#drawer": {
_44
"children": [
_44
"product-summary-column#drawer-col2",
_44
"product-comparison-block.close-button"
_44
],
_44
"props": {
_44
"blockClass": "drawer-summary"
_44
}
_44
},
_44
"product-summary-column#drawer-col2": {
_44
"children": ["product-summary-name", "product-summary-price#comparison"],
_44
"props": {
_44
"blockClass": "drawer-summary-col2"
_44
}
_44
},
_44
"product-summary-price#comparison": {
_44
"props": {
_44
"showListPrice": false,
_44
"showSellingPriceRange": false,
_44
"showLabels": false,
_44
"showInstallments": false,
_44
"showDiscountValue": false
_44
}
_44
}

The code above is a default implementation of the Product Comparison component. To make any changes, declare the code above in your theme and perform the needed updates according to the available blocks.

Step 6 - Building the Product Comparison page

  1. In the /store/blocks folder, create a new file called product-comparison.json and include the following JSON:

_80
"store.custom#product-comparison-list": {
_80
"blocks": ["comparison-page"]
_80
},
_80
_80
"comparison-page": {
_80
"children": ["slider-layout-group#comparison-page"]
_80
},
_80
_80
"slider-layout-group#comparison-page": {
_80
"children": [
_80
"product-comparison-block.product-summary-row",
_80
"product-comparison-block.grouped-product-specifications"
_80
]
_80
},
_80
"product-comparison-block.product-summary-row": {
_80
"blocks": ["list-context.comparison-product-summary-slider#comparison-page"]
_80
},
_80
"list-context.comparison-product-summary-slider#comparison-page": {
_80
"blocks": ["product-summary.shelf.product-comparison#comparison-page"],
_80
"children": ["slider-layout#comparison-page-product-summary"]
_80
},
_80
"product-summary.shelf.product-comparison#comparison-page": {
_80
"children": [
_80
"flex-layout.row",
_80
"product-summary-image#comparison-page",
_80
"product-summary-name",
_80
"product-summary-space",
_80
"product-summary-price#comparison",
_80
"product-summary-buy-button"
_80
],
_80
"props": {
_80
"blockClass": "comparison-page-summary"
_80
}
_80
},
_80
"flex-layout.row": {
_80
"children": ["product-comparison-block.close-button"],
_80
"props": {
_80
"blockClass": "close",
_80
"horizontalAlign": "right"
_80
}
_80
},
_80
"product-summary-image#comparison-page": {
_80
"props": {
_80
"width": 200,
_80
"heightProp": 200
_80
}
_80
},
_80
"product-comparison-block.grouped-product-specifications": {
_80
"blocks": ["list-context.comparison-row#comparison-page-row"]
_80
},
_80
"list-context.comparison-row#comparison-page-row": {
_80
"children": ["slider-layout#comparison-no-arrows"]
_80
},
_80
"slider-layout#comparison-page-product-summary": {
_80
"props": {
_80
"blockClass": "comparison-page",
_80
"itemsPerPage": {
_80
"desktop": 4,
_80
"tablet": 3,
_80
"phone": 1
_80
},
_80
"showPaginationDots": "never",
_80
"infinite": true,
_80
"fullWidth": true
_80
}
_80
},
_80
"slider-layout#comparison-no-arrows": {
_80
"props": {
_80
"itemsPerPage": {
_80
"desktop": 4,
_80
"tablet": 3,
_80
"phone": 1
_80
},
_80
"showPaginationDots": "never",
_80
"infinite": true,
_80
"fullWidth": true,
_80
"blockClass": "comparison-page",
_80
"showNavigationArrows": "never"
_80
}
_80
}

  1. In the theme's routes.json file, add a new route for the Product Comparison page:

_10
+{
_10
+ "store.custom#product-comparison-list": {
_10
+ "path": "/product-comparison"
_10
+ }
_10
+}

product-comparison-block.grouped-product-specifications props

Prop nameTypeDescriptionDefault value
productSpecificationsToHide[string]List of product fields that should be hidden in the Product Comparison page. The desired product fields must be separated by a comma.undefined
productSpecificationGroupsToHide[string]List of product specification groups that should be hidden on the Product Comparison page. The desired product specification groups must be separated by a comma.undefined

product-comparison-block.product-specifications props

Prop nameTypeDescriptionDefault value
productSpecificationsToHide[string]List of product fields that should be hidden in the Product Comparison page. The desired product fields must be separated by a comma.undefined

product-comparison-block.sku-specifications props

Prop nameTypeDescriptionDefault value
skuSpecificationsToHide[string]List of SKU specification fields that should be hidden on the Product Comparison page. The desired SKU specification fields must be separated by a comma.undefined

product-comparison-block.product-summary-row props

Prop nameTypeDescriptionDefault value
isShowDifferenceDefaultbooleanSet the "show only differences" checkbox to true as the default value on the comparison page.false
=======

Step 7 - Change the comparison bucket size

This is an optional configuration, so you can set a fixed number in the app configuration to change the maximum number of items in the comparison bucket. The default value is 10 items; if you exceed the maximum limit, you will receive a notification.

Instructions

  1. Go to /admin/apps, then find the Product Comparison app under Installed apps.
  2. Click Settings.
  3. Enter the maximum comparison bucket size for your application.

Customization

To apply CSS customizations in this and other blocks, follow the instructions in Using CSS Handles for store customization.

CSS Handles
closeButton
closeButtonContainer
compareProductsButton
comparisonButtons
comparisonCol
drawer
drawerContainer
expandCollapseButton
fieldNameCol
fieldNameCol
productFieldValue
productSelectorContainer
productSpecificationValue
productSpecificationValues
productSummaryRowContainer
rowContainer
showDifferencesContainer
skuFieldValue
skuSpecificationValue
skuSpecificationValues
title
removeAllItemsButtonWrapper
compareProductButtonWrapper
removeAllWrapper
drawerTitleOuterContainer
drawerTitleInnerContainer
drawerOpened
drawerClosed
See also
VTEX App Store
VTEX IO Apps