Documentation
Feedback
Guides
VTEX IO Apps

VTEX IO Apps
Basic components
Product Customizer
Official extension
Version: 2.12.4
Latest version: 2.12.4

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

The Product Customizer component can be used on the Product Details Page (PDP) to display attachments and/or a subscription form.

An attachment is the optional and cost-free customization of a product.

{"base64":"  ","img":{"width":2878,"height":1638,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":927135,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-product-customizer-0.png"}}
Example of a PDP with the Product Customizer component displaying product attachments.

Product subscriptions facilitate recurring sales by automatically scheduling the purchase of a specific product at the frequency requested by the customer.

{"base64":"  ","img":{"width":2860,"height":1438,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":526825,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-product-customizer-1.gif"}}
Example of a PDP with the Product Customizer component displaying the product subscription.

Before you start

  • If you plan to use the Product Customizer component to display attachments, make sure to set up Assembly Options.
  • If you plan to use the Product Customizer component to display a subscription form, make sure to set up Subscriptions. The Product Customizer integration with the Subscription module is native and will be automatically enabled when subscription settings are detected.

Configuring Product Customizer

  1. Add the product-customizer app to your theme dependencies in the manifest.json. For example:

_10
dependencies: {
_10
+ "vtex.product-customizer": "2.x"
_10
}

  1. Add the product-assembly-options block as a child of the store.product template (PDP template). This is enough to enable the subscription form.

_11
"store.product": {
_11
"children": [
_11
"flex-layout.row#product-breadcrumb",
_11
"flex-layout.row#product-main",
_11
"flex-layout.row#description",
_11
"shelf.relatedProducts",
_11
"product-reviews",
_11
"product-questions-and-answers",
_11
+ "product-assembly-options"
_11
]
_11
},

  1. Declare the product-assembly-options props for your scenario.

Displaying attachments (optional)

  1. To display attachments of a product on the Product Detail Page (PDP), declare the product-assembly-options block and add the assembly-option-input-values block as its child.

_10
"product-assembly-options": {
_10
"children": [
_10
"assembly-option-input-values"
_10
]
_10
},

  1. Use the blocks exported by the product-customizer app to create a solution that best suits your specific scenario.
Block nameDescription
assembly-option-item-imageDisplays the attachment image.
assembly-option-item-quantity-selectorDisplays a quantity selector.
assembly-option-item-nameDisplays the attachment name.
assembly-option-item-priceDisplays the attachment price.
assembly-option-item-customizeDisplays the Customize button. When clicked, it opens a modal that allows customers to customize the attachment.
assembly-option-item-children-descriptionDisplays a summary with all selected attachments.
  1. Declare the props for the chosen blocks according to your scenario. For example:

_10
"product-assembly-options": {
_10
"props":{
_10
"initiallyOpened": "always"
_10
},
_10
"children": [
_10
"flex-layout.row#product-assembly-options",
_10
"assembly-option-input-values"
_10
]
_10
},

While building your solution, note that you can receive inputs from three types of attachments:

  • Predefined options: Predefined attachment options set in the Permitted Values field. Set up the optionsDisplay prop from the assembly-option-input-values block to define how these options are displayed.
  • Free text: Text input. Depending on the value set in the Maximum Number of Characters field in the attachment settings, shoppers may or may not have a character limit for this attachment.
  • Boolean: Boolean attachment options set in the Permitted Values field. Customers can select the attachment by clicking the checkbox.

Check the following example where the three attachment types are implemented:

{"base64":"  ","img":{"width":1180,"height":736,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":64908,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-product-customizer-2.png"}}

Check out below how the product attachment displayed above was added to the Catalog:

{"base64":"  ","img":{"width":2268,"height":1088,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":189056,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-product-customizer-3.png"}}

When an attachment is set as required, all attachment options are automatically made available to consumers. On the other hand, if an attachment is not required, the Add customization button is rendered, as shown in the example above. This gives shoppers the option to add or not an attachment to their product.

Also, keep in mind that the Checkout does not natively display the customized product option selected by the customer. To display the product in the Checkout with the selected attachments, it is necessary to customize the Checkout page, allowing it to read and render product information.

Props

product-assembly-options props

Prop nameTypeDescriptionDefault value
initiallyOpenedenumDefines whether the customization box will be opened even if an attachment is not required (always) or if the customization box will be opened only if the attachment is required (required).required

assembly-option-input-values props

Prop nameTypeDescriptionDefault value
optionsDisplayenumDefines whether a checkbox (box) or a dropdown list (select) will be used to select the attachment pre-defined options.select

assembly-option-item-customizeprops

Prop nameTypeDescriptionDefault value
buttonPropsobjectDefines the behavior of the Customize button. In addition to the collapse prop, the buttonProps object can include child blocks to build the content of the modal triggered when the button is clicked.undefined
  • buttonProps object:
Prop nameTypeDescriptionDefault value
collapseenumCustomize button positioning. Possible values are: left or right.left

Customization

To apply CSS customizations to this and other blocks, please see the Using CSS handles for store customization guide.

CSS handles
booleanInputValue
inputValueOptionBox
itemContainer
modalViewDoneButton
modalViewProductContainer
modalViewProductImage
modalViewProductInfos
modalViewProductName
multipleItemQuantitySelector
optionsInputValue
optionsInputValueDropdown
optionsInputValueLabel
optionsInputValueLabelContainer
optionsInputValueOptionBoxContainer
productAssemblyGroupName
productAssemblyGroupNameRow
productAssemblyGroupRequiredTag
productAssemblyOptionItemCustomize
productAssemblyOptionItemCustomize__label
productAssemblyOptionItemImage
productAssemblyOptionItemName
textInputValue
See also
VTEX App Store
VTEX IO Apps