VTEX Developer Portal

The list-context.product-list interface is a instance of the list-context interfaces, which means its part of a set of special interfaces that enables you to create lists of content that can be edited via Site Editor.

In order to create a list of products, you need to use the list-context.product-list block and a product-summary.shelf.


This block is used to specify what variation of product-summary to be used to create the list of products, and the list-context.product-list you want as follows:

  "product-summary.shelf#demo1": {
    "children": [
  "list-context.product-list#demo1": {
    "blocks": ["product-summary.shelf#demo1"],
    "children": ["slider-layout#demo-products"]

list-context.product-list is also responsible for performing the GraphQL query that fetches the list of products, so it can receive the following props:

Prop nameTypeDescriptionDefault value
categoryStringCategory ID of the listed items. For sub-categories, use "/" (e.g. "1/2/3")-
specificationFiltersArray({ id: String, value: String })Specification Filters of the listed items.[]
collectionStringFilter by collection.-
orderByEnumOrdination type of the items. Possible values: '', OrderByTopSaleDESC, OrderByReleaseDateDESC, OrderByBestDiscountDESC, OrderByPriceDESC, OrderByPriceASC, OrderByNameASC, OrderByNameDESCOrderByTopSaleDESC
hideUnavailableItemsBooleanHides items that are unavailable.false
maxItemsNumberMaximum items to be fetched.10
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"
installmentCriteriaInstallmentCriteriaEnumControl what price to be shown when price has different installments options."MAX_WITHOUT_INTEREST"
listNameStringName of the list property on Google Analytics events.``
preferredSKUPreferredSKUEnumControls which SKU will be selected in the summary"FIRST_AVAILABLE"

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 InstallmentCriteriaEnum:

Maximum without interestMAX_WITHOUT_INTERESTWill display the maximum installment option with no interest.
MaximumMAX_WITH_INTERESTWill display the maximum installment option having interest or not.

For PreferredSKUEnum:

First AvailableFIRST_AVAILABLESelects the first available SKU in stock it finds.
Last AvailableLAST_AVAILABLESelects the last available SKU in stock it finds.
CheapestPRICE_ASCSelects the cheapest SKU in stock it finds.
Most ExpensivePRICE_DESCSelects the most expensive SKU in stock it finds.

⚠️ There's a way to select which SKU should take preference over this prop. You can create a Product (field) specification and per product assign the value of the desired SKU to be initially selected. Keep in mind that If the specification doesn't exist or if the value is empty, it will use the preferredSKU prop as fallback. You can read more about it, and how to implement it in Recipes

Updated about a month ago


Suggested Edits are limited on API Reference Pages

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