All ContributorsAll Contributors

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.

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

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

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

Before you start

  • If you'll use the Product Customizer component to display attachments, set up Assembly Options.
  • If you'll use the Product Customizer component to display a subscription form, set up Subscriptions. The Product Customizer's integration with the Subscription module is native and automatically enabled when subscriptions settings are detected.


  1. Add the product-customizer app to your theme's dependencies in the manifest.json, for example:
  dependencies: {
+   "vtex.product-customizer": "2.x"
  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.
  "store.product": {
    "children": [
+     "product-assembly-options"
  1. Declare the product-assembly-options props according to your scenario.

Displaying attachments (Optional)

  1. Declare the product-assembly-options block and add the assembly-option-input-values block as its child to display the attachments of a product on the PDP.
  "product-assembly-options": {
    "children": [
  1. Use the blocks exported by the product-customizer app to build the most suitable solution for your 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 shoppers to customize the attachment.
assembly-option-item-children-descriptionDisplays a summary with all attachments selected.
  1. Declare the props for the chosen blocks according to your scenario. For example:
"product-assembly-options": {
   "initiallyOpened": "always"
 "children": [

While building your solution, notice 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 Maximum Number of Characters field in the attachment settings, shoppers may or may not face a character limit.
  • Boolean - Boolean attachment options set in the Permitted Values field. Shoppers can select the attachment by simply clicking on a checkbox.

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


Check out below how the product attachment displayed above was registered in the Catalog:


It's worth noting that when an attachment is registered as required, all attachment options are automatically made available to shoppers. If an attachment is not required, the Add customization button is rendered as in the example above, giving shoppers the option to add or not an attachment to their product.

Also, keep in mind that the Checkout doesn't natively display the customized product option selected by the shopper. To display the product in the Checkout with the selected attachments, it's necessary to customize the Checkout page, allowing it to read and render product data.


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's pre-defined


Prop nameTypeDescriptionDefault value
buttonPropsobjectDefines the behavior of the Customize button. 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


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

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?