📢 Don't fork this project. Use, contribute, or open issues through Store Discussion.


The Shelf is a theme block responsible for showing a collection of products in the home page.



  1. Import the Shelf app to your theme's dependencies on the manifest.json, for example:
  dependencies: {
    "vtex.shelf": "1.x"
  1. Add the shelf block into your theme. The Shelf block queries a list of products and it can be added into any template of your theme. For it to properly function, the Product Summary also needs to be added to the Shelf. Check an implementation example below:
  "shelf": {
    "blocks": ["product-summary.shelf"],
    "props": {
      "category": 1,
      "orderBy": "OrderByTopSaleDESC",
      "paginationDotsVisibility": "desktopOnly",
      "productList": {
        "maxItems": 8,
        "itemsPerPage": 4,
        "minItemsPerPage": 1,
        "scroll": "BY_PAGE",
        "arrows": true,
        "titleText": "Top sellers"
  "product-summary": {
  "props": {
    "isOneClickBuy": false,
    "showBadge": true,
    "badgeText": "OFF",
    "displayBuyButton": "displayButtonHover",
    "showCollections": false,
    "showListPrice": true,
    "showLabels": false,
    "showInstallments": true,
    "showSavings": true


⚠️ RelatedProducts is a subtype of a Shelf block (shelf.relatedProduct) that queries and displays the related products on a Product Details Page. It can therefore only be declared in a product template (store.product), for example:

  "store.product": {
    "children": [


Prop nameTypeDescriptionDefault value
categoryStringCategory ID of the listed items in the shelf. For sub-categories, use "/" before the ID.-
specificationFiltersArray(SpecificationFilterItem)Specification Filters of the listed items in the shelf. )[]
collectionStringInput a collection ID to display products from a collection.-
orderByEnumOrdenation type of the items in the shelf. Possible values: OrderByTopSaleDESC, OrderByReleaseDateDESC, OrderByBestDiscountDESC, OrderByPriceDESC, OrderByPriceASC, OrderByNameASC, OrderByNameDESC or '' (default value by relevance)''
hideUnavailableItemsBooleanHides items that are unavailable.false
skusFilterSkusFilterEnumControl SKUs returned for each product in the query. The less SKUs needed to be returned, the more performant your shelf query will be."ALL_AVAILABLE"
paginationDotsVisibilityEnumControls if pagination dots below the Shelf should be rendered or not. Possible values: visible (always show), hidden (never show), desktopOnly, mobileOnlyvisible
productListProductListSchemaProduct list schema. For its configuration, you can check the ProductListSchema table below.-
  • For SkusFilterEnum:
First AvailableFIRST_AVAILABLEMost performant, ideal if you do not have a SKU selector in your shelf. Will return only the first available SKU for that product in your shelf query.
All AvailableALL_AVAILABLEA bit better performace, will only return SKUs that are available, ideal if you have a SKU selector but still want a better performance.
AllALLReturns all SKUs related to that product, least performant option.
  • For SpecificationFilterItem:
Prop nameTypeDescriptionDefault value
idStringID of Specification Filter to be searched for""
valueStringValue of Specification Filter to be searched for""

It is possible to add a related products shelf in a Product Details Page. Once its content depends on product data, the RelatedProductsblock can only be declared in a product template (store.product).


Prop nameTypeDescriptionDefault value
recommendationEnumType of recommendations that will be displayed in the Shelf. Possible values: similars, suggestion, accessories (these first three depend on the product's data given in the admin's catalog) and view, buy, viewandBought (These 3 are automatically generated according to the store’s activity)similars
productListProductListSchemaProduct list schema. See ProductListSchema-


Prop nameTypeDescriptionDefault value
maxItemsNumberMaximum number of items in the Shelf.10
scrollEnumSlide transition scroll type. Possible values: BY_PAGE, ONE_BY_ONEBY_PAGE
arrowsBooleanIf the arrows are displayable or not.true
showTitleBooleanIf a title should be displayed in the Shelf or not.true
titleTextStringShelf titlenull
summaryObjectProduct Summary schema properties.-
gapEnumGap between items. Possible values: ph0, ph3,ph5, ph7.ph3
minItemsPerPageNumberMinimum amount of slides to be on the screen, can be used to control how many itens will be displayed in the smallest screen size. This value can be a Float, which should be a multiple of 0.5 and would indicate that you want to show a "peek" of the next item in the Shelf.1
itemsPerPageNumberMaximum amount of slides to be on the screen. Can be used to control how many items will be displayed in the biggest screen size. This value can be a Float, which should be a multiple of 0.5 and would indicate that you want to show a "peek" of the next item in the Shelf.5


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