From 4287999989cb6153880af318abfcdc8d9a0b9200 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1rbara=20Celi?= <112641072+barbara-celi@users.noreply.github.com> Date: Wed, 20 May 2026 17:20:41 -0300 Subject: [PATCH 1/3] Enhance documentation for Product Summary List Updated Product Summary List documentation with installation, configuration, and props details. --- docs/ProductSummaryList.md | 74 +++++++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 25 deletions(-) diff --git a/docs/ProductSummaryList.md b/docs/ProductSummaryList.md index 9a102c32..875b9a32 100644 --- a/docs/ProductSummaryList.md +++ b/docs/ProductSummaryList.md @@ -1,14 +1,37 @@ # Product Summary List -The Product Summary List app (`list-context.product-list`) is an instance of the `list-context` interface, which provides predefined interfaces used to create content lists, such as a product list. +[ Source code](https://github.com/vtex-apps/product-summary/tree/master/react/components/ProductSummaryAttachmentList) + +The Product Summary List app (`list-context.product-list`) creates product lists in VTEX stores. It fetches product data and passes it to the `product-summary.shelf` block, which renders each product summary. + +Use this app to build shelves, product carousels, and other storefront sections that display products. ![list-context-example](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-product-summary-productsummarylist-0.png) -To create a product list, you must use the `list-context.product-list` and `product-summary.shelf` blocks. +## Installation + +1. [Install](https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-an-app) the [`product-summary`](https://developers.vtex.com/docs/apps/vtex.product-summary) app in your account by running the following command in your terminal: + + ```bash + vtex install vtex.product-summary + ``` + +## Configuration -## product-list-block +1. Open you [Store Theme](https://developers.vtex.com/docs/guides/vtex-io-documentation-store-theme) app in a code editor. +2. Open to [`manifest.json`](https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest) file and add the Product Summary List app (`vtex.product-summary`) under the [`dependencies`](https://developers.vtex.com/docs/guides/vtex-io-documentation-dependencies) field. -This block is used to specify the variation of `product-summary` that should be used to create the product list and the `list-context.product-list` you want, as follows: + ```json + "dependencies": { + "vtex.product-summary": "2.x" + } + ``` + +You can now use the `list-context.product-list` block, which is exported by the `product-summary` app. + +## `product-list` block + +Use this block to define the `product-summary` variation for creating the product list and the desired `list-context.product-list`, as shown below: ```json "product-summary.shelf#demo1": { @@ -27,43 +50,44 @@ This block is used to specify the variation of `product-summary` that should be }, ``` -`list-context.product-list` also runs the GraphQL query that fetches the product list, allowing it to receive the following props: +## Props + +The `list-context.product-list` also runs the GraphQL query that fetches the product list, allowing it to receive the following props: | Prop name | Type | Description | Default value | | ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | -| `category` | `string` | Category ID of the listed items. For subcategories, use "/" (example: "1/2/3"). | - | +| `category` | `string` | Category ID of the listed items. For subcategories, use `"/"` (example: `"1/2/3"`). | - | | `specificationFilters` | `Array({ id: String, value: String })` | Specification filters of the listed items. | [] | -| `collection` | `string` | Filter by collection. | - | -| `orderBy` | `enum` | Sort type of the items. Possible values are: `''`, `OrderByTopSaleDESC`, `OrderByReleaseDateDESC`, `OrderByBestDiscountDESC`, `OrderByPriceDESC`, `OrderByPriceASC`, `OrderByNameASC`, `OrderByNameDESC`. | `OrderByTopSaleDESC` | -| `hideUnavailableItems` | `boolean` | Hides unavailable items. | `false` | -| `maxItems` | `number` | Maximum items to be fetched. | `10` | -| `skusFilter` | [`SkusFilterEnum`](#skusfilterenum) | Control SKUs returned for each product in the query. The fewer SKUs that need to be returned, the more efficient your shelf query will be. Possible values are: `FIRST_AVAILABLE`, `ALL_AVAILABLE`, `ALL`. | `"ALL_AVAILABLE"` | -| `installmentCriteria` | [`InstallmentCriteriaEnum`](#installmentcriteriaenum) | Controls the price that will be displayed when the price has different installment options. Possible values are: `MAX_WITHOUT_INTEREST`, `MAX_WITH_INTEREST`. | `"MAX_WITHOUT_INTEREST"` | +| `collection` | `string` | ID of the product collection to be displayed. | - | +| `orderBy` | `enum` | Sort order for the items. Possible values are: `''`, `OrderByTopSaleDESC`, `OrderByReleaseDateDESC`, `OrderByBestDiscountDESC`, `OrderByPriceDESC`, `OrderByPriceASC`, `OrderByNameASC`, `OrderByNameDESC`. | `OrderByTopSaleDESC` | +| `hideUnavailableItems` | `boolean` | Hides unavailable items when set to `true`. | `false` | +| `maxItems` | `number` | Maximum number items to be fetched. | `10` | +| `skusFilter` | [`SkusFilterEnum`](#skusfilterenum) | Controls which SKUs are returned for each product. The fewer SKUs that need to be returned, the more efficient your shelf query will be. Possible values are: `FIRST_AVAILABLE`, `ALL_AVAILABLE`, `ALL`. | `"ALL_AVAILABLE"` | +| `installmentCriteria` | [`InstallmentCriteriaEnum`](#installmentcriteriaenum) | Controls which price is displayed when a product has multiple installment options. Possible values are: `MAX_WITHOUT_INTEREST`, `MAX_WITH_INTEREST`. | `"MAX_WITHOUT_INTEREST"` | | `listName` | `string` | Name of the list property in Google Analytics events. | - | -| `preferredSKU` | [`PreferredSKUEnum`](#preferredskuenum) | Controls the SKU that will be selected in the summary. Possible values are: `FIRST_AVAILABLE`, `LAST_AVAILABLE`, `PRICE_ASC`, `PRICE_DESC`. | `"FIRST_AVAILABLE"` | +| `preferredSKU` | [`PreferredSKUEnum`](#preferredskuenum) | Defines which SKU is selected in the summary. Possible values are: `FIRST_AVAILABLE`, `LAST_AVAILABLE`, `PRICE_ASC`, `PRICE_DESC`. | `"FIRST_AVAILABLE"` | -### `SkusFilterEnum`: +### `SkusFilterEnum` | Name | Value | Description | | --------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | First Available | `FIRST_AVAILABLE` | Best performance, ideal if you don't have a SKU selector on your shelf. It returns only the first available SKU for that product in your shelf query. | -| All Available | `ALL_AVAILABLE` | Somewhat better performance. It only returns available SKUs, which is ideal if you have a SKU selector but still want better performance. | -| All | `ALL` | Returns all SKUs related to the product. This is the least efficient option. | +| All Available | `ALL_AVAILABLE` | It only returns available SKUs. Ideal if you have a SKU selector but want better performance. | +| All | `ALL` | Lowest performance. Returns all SKUs associated with the product, including unavailable ones. | -### `InstallmentCriteriaEnum`: +### `InstallmentCriteriaEnum` | Name | Value | Description | | ------------------------ | ---------------------- | ----------------------------------------------------------------- | -| Maximum without interest | `MAX_WITHOUT_INTEREST` | Displays the maximum installment option with no interest. | -| Maximum | `MAX_WITH_INTEREST` | Displays the maximum installment option with or without interest. | +| Maximum without interest | `MAX_WITHOUT_INTEREST` | Displays the maximum number of installments with no interest. | +| Maximum | `MAX_WITH_INTEREST` | Displays the maximum number of installments, including those with interest. | -### `PreferredSKUEnum`: +### `PreferredSKUEnum` | Name | Value | Description | | --------------- | ----------------- | -------------------------------------------------- | -| First Available | `FIRST_AVAILABLE` | Selects the first available SKU it finds. | -| Last Available | `LAST_AVAILABLE` | Selects the last available SKU it finds. | -| Cheapest | `PRICE_ASC` | Selects the cheapest SKU in stock it finds. | -| Most Expensive | `PRICE_DESC` | Selects the most expensive available SKU it finds. | +| First Available | `FIRST_AVAILABLE` | Selects the first available SKU. | +| Last Available | `LAST_AVAILABLE` | Selects the last available SKU. | +| Most Expensive | `PRICE_DESC` | Selects the most expensive available SKU. | -> ⚠️ To select the SKU that will take precedence over this prop, create a Product (field) specification and assign the value of the desired SKU to be initially set for each product. If the specification doesn't exist or the value is empty, the `preferredSKU` prop will be used as a fallback. For more information, see [Configuring custom images for the SKU Selector](https://developers.vtex.com/docs/guides/vtex-io-documentation-configuring-custom-images-for-the-sku-selector). +> ⚠️ To override the `PreferredSKU` prop, create a Product specification and assign the value of the SKU you want selected by default for each product. If the specification doesn't exist or the value is empty, the `preferredSKU` prop is used as a fallback. From 8e1b5f2aaa5b65fa36ca19e5a081103f917b9d56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1rbara=20Celi?= <112641072+barbara-celi@users.noreply.github.com> Date: Mon, 15 Jun 2026 11:05:01 -0300 Subject: [PATCH 2/3] Update docs/ProductSummaryList.md Co-authored-by: Henrique Balbino --- docs/ProductSummaryList.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ProductSummaryList.md b/docs/ProductSummaryList.md index 875b9a32..8b2f305e 100644 --- a/docs/ProductSummaryList.md +++ b/docs/ProductSummaryList.md @@ -54,8 +54,8 @@ Use this block to define the `product-summary` variation for creating the produc The `list-context.product-list` also runs the GraphQL query that fetches the product list, allowing it to receive the following props: -| Prop name | Type | Description | Default value | -| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | +| Prop name | Type | Description | Default value | +| ---------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `category` | `string` | Category ID of the listed items. For subcategories, use `"/"` (example: `"1/2/3"`). | - | | `specificationFilters` | `Array({ id: String, value: String })` | Specification filters of the listed items. | [] | | `collection` | `string` | ID of the product collection to be displayed. | - | From 814f2484067c6ceaf950159a5d08c9737bf74f0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1rbara=20Celi?= <112641072+barbara-celi@users.noreply.github.com> Date: Mon, 15 Jun 2026 11:05:52 -0300 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Henrique Balbino --- docs/ProductSummaryList.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/ProductSummaryList.md b/docs/ProductSummaryList.md index 8b2f305e..c18f565a 100644 --- a/docs/ProductSummaryList.md +++ b/docs/ProductSummaryList.md @@ -56,38 +56,38 @@ The `list-context.product-list` also runs the GraphQL query that fetches the pro | Prop name | Type | Description | Default value | | ---------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -| `category` | `string` | Category ID of the listed items. For subcategories, use `"/"` (example: `"1/2/3"`). | - | -| `specificationFilters` | `Array({ id: String, value: String })` | Specification filters of the listed items. | [] | -| `collection` | `string` | ID of the product collection to be displayed. | - | -| `orderBy` | `enum` | Sort order for the items. Possible values are: `''`, `OrderByTopSaleDESC`, `OrderByReleaseDateDESC`, `OrderByBestDiscountDESC`, `OrderByPriceDESC`, `OrderByPriceASC`, `OrderByNameASC`, `OrderByNameDESC`. | `OrderByTopSaleDESC` | -| `hideUnavailableItems` | `boolean` | Hides unavailable items when set to `true`. | `false` | -| `maxItems` | `number` | Maximum number items to be fetched. | `10` | -| `skusFilter` | [`SkusFilterEnum`](#skusfilterenum) | Controls which SKUs are returned for each product. The fewer SKUs that need to be returned, the more efficient your shelf query will be. Possible values are: `FIRST_AVAILABLE`, `ALL_AVAILABLE`, `ALL`. | `"ALL_AVAILABLE"` | -| `installmentCriteria` | [`InstallmentCriteriaEnum`](#installmentcriteriaenum) | Controls which price is displayed when a product has multiple installment options. Possible values are: `MAX_WITHOUT_INTEREST`, `MAX_WITH_INTEREST`. | `"MAX_WITHOUT_INTEREST"` | -| `listName` | `string` | Name of the list property in Google Analytics events. | - | -| `preferredSKU` | [`PreferredSKUEnum`](#preferredskuenum) | Defines which SKU is selected in the summary. Possible values are: `FIRST_AVAILABLE`, `LAST_AVAILABLE`, `PRICE_ASC`, `PRICE_DESC`. | `"FIRST_AVAILABLE"` | +| `category` | `string` | Category ID of the listed items. For subcategories, use `"/"` (example: `"1/2/3"`). | - | +| `specificationFilters` | `Array({ id: String, value: String })` | Specification filters of the listed items. | `[]` | +| `collection` | `string` | ID of the product collection to be displayed. | - | +| `orderBy` | `enum` | Sort order for the items. Possible values are: `''`, `OrderByTopSaleDESC`, `OrderByReleaseDateDESC`, `OrderByBestDiscountDESC`, `OrderByPriceDESC`, `OrderByPriceASC`, `OrderByNameASC`, `OrderByNameDESC`. | `OrderByTopSaleDESC` | +| `hideUnavailableItems` | `boolean` | Hides unavailable items when set to `true`. | `false` | +| `maxItems` | `number` | Maximum number items to be fetched. | `10` | +| `skusFilter` | [`SkusFilterEnum`](#skusfilterenum) | Controls which SKUs are returned for each product. The fewer SKUs that need to be returned, the more efficient your shelf query will be. Possible values are: `FIRST_AVAILABLE`, `ALL_AVAILABLE`, `ALL`. | `"ALL_AVAILABLE"` | +| `installmentCriteria` | [`InstallmentCriteriaEnum`](#installmentcriteriaenum) | Controls which price is displayed when a product has multiple installment options. Possible values are: `MAX_WITHOUT_INTEREST`, `MAX_WITH_INTEREST`. | `"MAX_WITHOUT_INTEREST"` | +| `listName` | `string` | Name of the list property in Google Analytics events. | - | +| `preferredSKU` | [`PreferredSKUEnum`](#preferredskuenum) | Defines which SKU is selected in the summary. Possible values are: `FIRST_AVAILABLE`, `LAST_AVAILABLE`, `PRICE_ASC`, `PRICE_DESC`. | `"FIRST_AVAILABLE"` | ### `SkusFilterEnum` | Name | Value | Description | -| --------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | First Available | `FIRST_AVAILABLE` | Best performance, ideal if you don't have a SKU selector on your shelf. It returns only the first available SKU for that product in your shelf query. | -| All Available | `ALL_AVAILABLE` | It only returns available SKUs. Ideal if you have a SKU selector but want better performance. | +| All Available | `ALL_AVAILABLE` | It only returns available SKUs. Ideal if you have a SKU selector but want better performance. | | All | `ALL` | Lowest performance. Returns all SKUs associated with the product, including unavailable ones. | ### `InstallmentCriteriaEnum` | Name | Value | Description | -| ------------------------ | ---------------------- | ----------------------------------------------------------------- | -| Maximum without interest | `MAX_WITHOUT_INTEREST` | Displays the maximum number of installments with no interest. | +| ------------------------ | ---------------------- | --------------------------------------------------------------------------- | +| Maximum without interest | `MAX_WITHOUT_INTEREST` | Displays the maximum number of installments with no interest. | | Maximum | `MAX_WITH_INTEREST` | Displays the maximum number of installments, including those with interest. | ### `PreferredSKUEnum` -| Name | Value | Description | -| --------------- | ----------------- | -------------------------------------------------- | -| First Available | `FIRST_AVAILABLE` | Selects the first available SKU. | -| Last Available | `LAST_AVAILABLE` | Selects the last available SKU. | -| Most Expensive | `PRICE_DESC` | Selects the most expensive available SKU. | +| Name | Value | Description | +| --------------- | ----------------- | ----------------------------------------- | +| First Available | `FIRST_AVAILABLE` | Selects the first available SKU. | +| Last Available | `LAST_AVAILABLE` | Selects the last available SKU. | +| Most Expensive | `PRICE_DESC` | Selects the most expensive available SKU. | > ⚠️ To override the `PreferredSKU` prop, create a Product specification and assign the value of the SKU you want selected by default for each product. If the specification doesn't exist or the value is empty, the `preferredSKU` prop is used as a fallback.