VTEX Developer Portal

The Product Gifts app provides blocks responsible for displaying, in the Product Description block, all gifts available for a given product.

:information_source: A product's gift is configured in a Buy&Win promotion

product-giftproduct-gift

Configuration

  1. Add the product-gifts app to your theme's dependencies in the manifest.json. For example:
"dependencies": {
  "vtex.product-gifts": "0.x"
}

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

Block nameDescription
product-giftsmandatorymandatory Renders a default Product Gifts block implementation.
gift-textmandatorymandatory Reads Catalog data regarding the product's gifts and provides it to its children.
product-gift-listRenders the available gifts in a list format. It also provides context for its 3 children listed below.
gift-nameRenders the product's gift name.
gift-imageRenders the product's gift image.
gift-descriptionRenders the gift's description provided by the product-gift-list block.
  1. Add the product-gifts block to your store.product template:
"store.product": {
  "children": [
    // (...)
    "product-gifts",
  ]
}

When added to the store.product template but not declared with any children or prop, the Product Gifts block is rendered even so.

For the rendering, it uses the following block implementation behind the scenes:

{
  "product-gifts": {
    "props": {
      "maxVisibleItems": {
        "desktop": 2,
        "mobile": 1
      }
    },
    "children": ["flex-layout.row#product-gifts-text", "product-gift-list"]
  },

  "flex-layout.row#product-gifts-text": {
    "props": {
      "verticalAlign": "middle",
      "colSizing": "auto",
      "preserveLayoutOnMobile": true
    },
    "children": [
      "rich-text#product-gifts",
      "flex-layout.col#product-gifts-text"
    ]
  },
  "flex-layout.col#product-gifts-text": {
    "children": ["gift-text"],
    "props": {
      "verticalAlign": "middle"
    }
  },
  "rich-text#product-gifts": {
    "props": {
      "text": "**+ GIFT**"
    }
  },
  "gift-text": {
    "props": {
      "text": "{exceedingItems, plural, =0{ } one {+ # gift} other {+ # gifts}}"
    }
  },
  "product-gift-list": {
    "children": ["flex-layout.row#gift"]
  },
  "flex-layout.row#gift": {
    "props": {
      "fullWidth": true
    },
    "children": ["flex-layout.col#gift-name-description", "gift-image"]
  },
  "flex-layout.col#gift-name-description": {
    "props": {
      "verticalAlign": "middle",
      "rowGap": 3
    },
    "children": ["gift-name", "gift-description"]
  }
}

Advanced configuration

If desired, you can change the Product Gifts default implementation by explicitly declaring the code showed above in your store.product template.

As a result, you will be able to configure the Product Gifts behavior by using all available props for each block:

  • product-gifts

product-giftsproduct-gifts

Prop nameTypeDescriptionDefault value
maxVisibleItemsnumber | "showAll"Maximum number of gifts that will be displayed at once"showAll"
  • gift-text

gift-textgift-text

Prop nameTypeDescriptionDefault value
textStringA translatable string (according to ICU pattern) that has variables that might be used to render any desired text regarding the gifts."{exceedingItems, plural, =0{ } one {+ # gift} other {+ # gifts}}"

You can configure the string received by the text prop using the following variables:

Variable nameDescription
exceedingItemsNumber of items that were not rendered because of the maxVisibleItems prop of product-gifts.
totalGiftsTotal number of gifts available.
visibleItemsNumber of items that are being rendered.
  • gift-name

gift-namegift-name

Prop nameTypeDescriptionDefault value
linkToProductPageBooleanWhether or not the gift-name block should be a link to the gift's product page.false
nameTypeenumName type to be displayed alongside the gift. Possible values are: productName (displays the gift's product name) and skuName (displays the gift's SKU name).skuName
  • gift-image

gift-imagegift-image

Prop nameTypeDescriptionDefault value
maxWidthNumber | StringGift image maximum width.125
maxHeightNumber | StringGift image maximum height.125
minWidthNumber | StringGift image minimum width.125
minHeightNumber | StringGift image minimum height.125
imageLabelStringThe label of the image that should be rendered.undefined

:information_source: If no image label is defined, the gift-image block will use the first available image from the product's SKU.

Customization

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.

Thereafter, you should add a single column table with the available CSS handles for that block:

CSS Handles
giftDescription
giftListItem
giftNameLink
giftNameText
productGiftListContainer
productGiftText
productGiftsContainer

Updated 5 months ago


Product Gifts


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.