All ContributorsAll Contributors

The Product Customizer allows a product's attachments and/or its subscription to be made available and ready to be defined by users on the product details page.

Example of a product details page with the Product Customizer component displaying the product's attachments.

Example of a product details page with the Product Customizer component displaying the product subscription.

*The Product Customizer's integration with the Subscription module is native and automatically enabled by the component. In order to allow your users to set the subscription on the product details page, set up the Subscription v2 in your VTEX account and follow the instructions below to implement the Product Customizer app.*


  1. Add product-customizer app to your theme's dependencies in the manifest.json, for example:
  dependencies: {
+   "vtex.product-customizer": "2.x"

Now, you are able to use all blocks exported by the product-customizer app. Check out the full list below:

Block nameDescription
product-assembly-options Top level block responsible for displaying the product customizer default component, showing product's attachments. Use this block's children list to define which attachment data you want to display for users.
assembly-option-input-values Displays a checkbox or a dropdown list field so users can choose the desired attachment for their products.
assembly-option-item-imageRenders the attachment image.
assembly-option-item-quantity-selectorRenders a quantity selector.
assembly-option-item-nameRenders the attachment name.
assembly-option-item-priceRenders the attachment price.
assembly-option-item-customizeRenders a button Customize that when clicked on opens a modal to customize the attachment.
assembly-option-item-children-descriptionRenders a summary with all attachments selected.
  1. In the theme's product template (store.product), add the product-assembly-options block to the children list. This will be enough to display the subscription options for the products if the Subscription v2 was previously configured in your VTEX account.
  "store.product": {
    "children": [
  1. Declare the product-assembly-options block and add the assembly-option-input-values block as its child to display the product's attachments on the product details page.
  "product-assembly-options": {
    "children": [

Notice that you can use other blocks, such as the assembly-option-item-image, as product-assembly-options's child in order to build the Product Customizer component most suitable for your desired scenario.

  1. Declare the blocks' props according to the desired scenario. For example:
 "product-assembly-options": {
   "initiallyOpened": "always"
 "children": [

product-assembly-options props

Prop nameTypeDescriptionDefault value
initiallyOpenedenumBy default, the customization box is opened if the attachment is required and closed if it's not. You can override this behavior by setting this prop to always, making it be opened even if the attachment is not required. Leave it as required for the default behavior.required

assembly-option-input-values props

Prop nameTypeDescriptionDefault value
optionsDisplayenumDefine whether the attachment's pre-defined options will be displayed to be selected in a Checkbox (box) or in a dropdown list (select) .select


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

Modus Operandi

According to the data entry in the catalog, the Product Customizer takes 3 types of attachments into account when being rendered:

  • Free text - Any text can be entered in this field. Users may or may not have a character limit, depending on what was filled in the Maximum Number of Characters field in the attachment register.
  • Predefined options - Users can only choose between an attachment's predefined options, according to what's set in the Permitted Values field in the attachment register. The way these options will be displayed can be defined with the optionsDisplay prop from assembly-option-input-values block.
  • Boolean - If the options that are predefined in the Permitted Values field are either true ou false, users can choose the attachment by simply clicking on a checkbox.

Notice the example below and check out the three attachment types simultaneously displayed for the same product:


Then, check out below how the product attachment displayed above was registered in the admin's Catalog:


Notice that when a product's attachment was registered as required, all attachment options will be automatically made available to users. If the product's attachment is not added as required, the Add customization button is rendered, as shown in the example above, giving users the options to add or not to add an attachment to their product.

The Product Customizer uses the new Assembly Options API (the traditional Attachments API will be discontinued). As a result, Checkout still doesn't natively render the customized product option previously selected by the user in the product page. For the product to be correctly displayed with the chosen attachment, it's necessary for now to customize the Checkout page interface for it to read the product data in its context and render it.


In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles

Contributors ✨

Thanks goes to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind are welcome!

Did this page help you?