VTEX Shelf

Description

The VTEX shelf app is a store component that shows a collection of products, and this app is used by store theme.

📢 Disclaimer: Don't fork this project; use, contribute, or open issue with your feature request.

Release schedule

ReleaseStatusInitial ReleaseMaintenance LTS StartEnd-of-lifeStore Compatibility
1.xCurrent Release2018-11-082.x
0.xMaintenance LTS2018-04-192018-11-08March 20191.x

See our LTS policy for more information.

Table of Contents

Usage

This app uses our store builder with the blocks architecture. To know more about Store Builder click here.

We add the shelf as a block in our Store.

To use this app you need to import it in your dependencies on the manifest.json.

1
2
3
  dependencies: {
    "vtex.shelf": "1.x"
  }

Then, add shelf block into your app theme as we do in our Store theme app.

Shelf Component queries a list of products and shows them. RelatedProducts is subtype of shelf component who queries and shows the related products.

Now, you can change the behavior of the shelf block that is in the store home. See an example of how to configure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
"shelf": {
  "props": {
    "orderBy": "OrderByTopSaleDESC",
    "productList": {
      "maxItems": 10,
      "itemsPerPage": 4,
      "scroll": "BY_PAGE",
      "arrows": true,
      "titleText": "New collection",
      "hideUnavailableItems": true,
      "summary": {
        "isOneClickBuy": false,
        "showBadge": true,
        "badgeText": "OFF",
        "buyButtonText": "Comprar",
        "displayBuyButton": "displayButtonHover",
        "showCollections": false,
        "showListPrice": true,
        "showLabels": false,
        "showInstallments": true,
        "showSavings": true,
        "name": {
          "showBrandName": false,
          "showSku": false,
          "showProductReference": false
        }
      }
    }
  }
}

Blocks API

When implementing this app as a block, various inner blocks may be available. The following interface lists the available blocks within shelf and related-products and describes if they are required or optional.

1
2
3
4
5
6
  "shelf": {
    "component": "Shelf"
  },
  "related-products": {
    "component": "RelatedProducts"
  }

Configuration

Through the Storefront, you can change the shelf's behavior and interface. However, you also can make in your theme app, as Store theme does.

For Shelf:

Prop nameTypeDescriptionDefault value
categoryStringCategory ID of the listed items in the shelf. For sub-categories, use "/" (e.g. "1/2/3")-
specificationFiltersArray(SpecificationFilterItem)Specification Filters of the listed items in the shelf. )[]
collectionNumberShows the remove button in each item-
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
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. See ProductListSchema-

For SpecificationFilterItem:

Prop nameTypeDescriptionDefault value
idStringid of Specification Filter to be searched for""
valueStringvalue of Specification Filter to be searched for""

For RelatedProducts:

Prop nameTypeDescriptionDefault value
recommendationEnumType of recommendations that is shown. Possible values: editor.relatedProducts.similars, editor.relatedProducts.view, editor.relatedProducts.buyeditor.relatedProducts.similars
productListProductListSchemaProduct list schema. See ProductListSchema-

ProductListSchema:

Prop nameTypeDescriptionDefault value
maxItemsNumberMaximum number of items in the shelf.10
scrollEnumScroll type of slide transiction. Possible values: BY_PAGE, ONE_BY_ONEBY_PAGE
arrowsBooleanIf the arrows are showable or not.true
showTitleBooleanShow title of the shelf.true
titleTextStringTitle of the shelf.null
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

For TabbedShelf:

Prop nameTypeDescriptionDefault value
isEnabledBooleanTrue if component should appearfalse
headlineStringText shown on top of component (leave empty to not display)''
bottomTextStringText shown on bottom of component (leave empty to not display)''
buttonTextStringText shown on button underneath the component (leave empty to not display the button)''
buttonUrlStringUrl to redirect user when button is pressed''
tabs[TabsSchemaItem]Tabs should be an array of items of type TabsSchemaItem.-
shelfShelfProps for the shelf displayed, same type as Shelf. See Shelf-

For TabsSchemaItem:

Prop nameTypeDescriptionDefault value
idStringid of category to be displayed-

"Since TabbedShelf props have a different structure, we add an example of usage below: "

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
"shelf.tabbed": {
    "blocks": [
      "product-summary"
    ],
    "props": {
      "isEnabled": true,
      "tabs": [
          {
            "id": 1,
            "__editorItemTitle": "Balls"
          },
          {
            "id": 2,
            "__editorItemTitle": "Clothes"
          },
          {
            "id": 3,
            "__editorItemTitle": "Underwear"
          }
        ],
      "shelf": {
        "orderBy": "OrderByTopSaleDESC",
        "productList": {
          "maxItems": 4,
          "itemsPerPage": 4,
          "scroll": "BY_PAGE",
          "arrows": false,
          "showTitle": false,
          "summary": {
            "displayBuyButton": "displayButtonAlways",
            "isOneClickBuy": true,
            "showBadge": true,
            "badgeText": "OFF",
            "buyButtonText": "Add to cart",
            "showCollections": false,
            "showListPrice": true,
            "showLabels": false,
            "showInstallments": false,
            "showSavings": false,
            "name": {
              "showBrandName": false,
              "showSku": false,
              "showProductReference": false
            }
          }
        }
      }
    }
  }

Also, you can configure the product summary that is defined on shelf. See here the Product Summary API.

Styles API

This app provides some CSS classes as an API for style customization.

To use this CSS API, you must add the styles builder and create an app styling CSS file.

  1. Add the styles builder to your manifest.json:
1
2
3
  "builders": {
    "styles": "1.x"
  }
  1. Create a file called vtex.shelf.css inside the styles/css folder. Add your custom styles:
1
2
3
.container {
  margin-top: 10px;
}

CSS namespaces

Below, we describe the namespaces that are defined in the Shelf and RelatedProducts.

Class nameDescriptionComponent Source
containerThe main container of Shelfindex
titleShelf title labelindex
relatedProductsThe main container of RelatedProductsindex
slideSlider in ShelfPopup

Troubleshooting

You can check if others are passing through similar issues here. Also feel free to open issues or contribute with pull requests.

Contributing

Check it out how to contribute with this project.

Tests

To execute our tests go to react/ folder and run yarn test

Travis CI

Build Status
Coverage Status