[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides list of controls for templates in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/store-framework)

---

(Legacy) CMS Portal

[Migrating your storefront from Legacy CMS Portal to Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/vtex-io-documentation-migrating-storefront-from-legacy-to-io)

[Can I order my product as I want?](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/can-i-order-my-product-as-i-want)

[List of controls for templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates)

[Setting up the zoom](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/setting-up-the-zoom)

[Creating gift lists](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/creating-gift-lists)

[Validating a layout before moving it to production](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/validating-a-layout-before-moving-it-to-production)

[How to use the page title control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/how-to-use-the-page-title-control)

[How product name control works](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/how-product-name-control-works)

[Configure the price history control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/configure-the-price-history-control)

[Shelf template controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/shelf-template-controls)

[Control to disable the canonical tag](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/control-to-disable-the-canonical-tag)

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/store-framework)

---

(Legacy) CMS Portal

[Migrating your storefront from Legacy CMS Portal to Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/vtex-io-documentation-migrating-storefront-from-legacy-to-io)

[Can I order my product as I want?](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/can-i-order-my-product-as-i-want)

[List of controls for templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates)

[Setting up the zoom](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/setting-up-the-zoom)

[Creating gift lists](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/creating-gift-lists)

[Validating a layout before moving it to production](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/validating-a-layout-before-moving-it-to-production)

[How to use the page title control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/how-to-use-the-page-title-control)

[How product name control works](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/how-product-name-control-works)

[Configure the price history control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/configure-the-price-history-control)

[Shelf template controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/shelf-template-controls)

[Control to disable the canonical tag](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/control-to-disable-the-canonical-tag)

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/storefront-best-practices)

---

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/storefront-development)

(Legacy) CMS Portal

[List of controls for templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates)

List of template controls

The controls listed in this article can be used by your store's frontend developer to create the store page layout in the **Storefront > Layout** module.

* [General controls](#general-controls)
* [Product page controls](#product-page-controls)
   * [RichSnippets controls](#richsnippets-controls)
* [Department, category, and search page controls](#department-category-and-search-page-controls)
* [Other controls](#other-controls)
* [Deprecated controls](#deprecated-controls)

## General controls

You can use the controls listed below in most pages in your store.

| Control                                      | Description                                                                                |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <vtex.cmc:breadCrumb/>                       | **Breadcrumb:** Indicates the user's current location in your store website and the pages they accessed to get to the current one. Works in product, department, category, and search pages.                                                                                |
| <vtex.cmc:fullTextSearchBox/>                | **Search control:** Displays the search bar in your store. For more information, read [Search Control - fulltextSearchBox](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-control-fulltextsearchbox).                                                                                |
| <vtex.cmc:welcomeMessage/>                   | **Welcome message:** Displays a welcome message to anyone visiting your store. To customize this message, go to the **Store Settings > Storefront** module and click **Settings**. In the Store Texts tab, look for the topbarSaudacao command in the ID options and select it. In the text box that will display automatically, you can edit the welcome message and then Save.                                                                                |
| <vtex:metaTags/>                             | **Meta tags:** Defines the page meta tags — tags that are useful for search engines to identify your content easily.                                                                                |
| <vtex.cmc:canonicalPage disable="true"/>     | **Disable canonical tag:** If this control is set to true, the canonical tag will be disabled in the page. Using this tag indicates duplicate content to search engines and prioritizes it correctly in page tracking.                                                                                |
| <vtex.cmc:departmentLinks/>                  | **Department links:** Displays links for the first level of categories (departments) created in the Admin. For the category to be listed, the Menu field must be enabled when [creating the category](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/registering-a-category--tutorials%5F206).                                                                                |
| <vtex.cmc:departmentNavigator/>              | **Department menu:** Displays a menu with your store departments and categories (levels 1 and 2). To display the link for the complete list, the Menu field must be enabled when [creating categories](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/registering-a-category--tutorials%5F206). This menu also displays brands that have the _[Display in Home menu](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/campos-de-cadastro-de-marca--37Ky7lTbEkiWIAYA80EMyI%23)_ option enabled and category specifications, such as size and color. This control is indicated for use as a side menu. |
| <vtex.cmc:searchTitle/>                      | **Page title:** Displays the title of departments, categories, and search pages.                                                                                |
| <vtex.cmc:productQuickView/>                 | **QuickView:** This control needs to be added before closing the </body> tag in the QuickView page template. It is key for loading the files needed in the page.                                                                                |
| <vtex.cmc:ProductQueryStringReferenceShelf/> | **Shelf:** Allows you to configure a shelf in your store using the attributes listed below.                                                                                |

Below, you can see a description of the **Shelf** control `<vtex.cmc:ProductQueryStringReferenceShelf/>` attributes:

| Tag attribute             | Description                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| layout                    | Shelf template ID. Required attribute.                                                                                |
| itemCount                 | Number of items to be displayed. Required attribute.                                                                             |
| columnCount               | Number of columns. Required attribute.                                                                                |
| showUnavailable           | The page will display out-of-stock products when this attribute is set to true.                                                  |
| selectionMode=”batch-buy” | Optional attribute that allows sorting products in bulk.                                                                         |
| isTrackable               | This control is trackable when this attribute is set to true.                                                                    |
| InternalCampaign          | Name of the internal [campaign audience](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/creating-campaign-audiences--6cnuDZJzIkIeocewAQQK4K). |
| InternalPart              | Internal _ViewPart_ name.                                                                                |

**Shelf** control example:

`1

<vtex.cmc:ProductQueryStringReferenceShelf layout="e2ed81f5-6241-4418-a47b-018d7482fcf0" itemCount="3" columnCount="3" showUnavailable="true" isTrackable="true" InternalCampaign="Landing highlight" InternalPart="Window display highlight"/>

`

## Product page controls

| Control                                             | Description                                                                                |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <vtex.cmc:ProductGifts />                           | **Display giveaways on the product page:** Displays the giveaways attached to the product, if you have configured a Buy One, Get One promotion in your store. [See how to configure this type of promotion](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/how-to-set-a-buy-and-win-promotion-gift-for-a-specific-sku--4QlFtwxAju6qOwaCi2YS0G).                                                                                |
| <vtex.cmc:productName/>                             | **Product name:** Displays the name of the product.                                                                                |
| <vtex.cmc:brandName/>                               | **Product brand with link:** Displays the product's brand with a link to access a list of products in the same brand and category in your store.                                                                                |
| <vtex.cmc:ProductImage/>                            | **Thumbnail of the main product image:** Displays a thumbnail of the main product image.                                                                                |
| <vtex.cmc:productReference/>                        | **Product reference code:** Displays the product reference code.                                                                                |
| <vtex.cmc:skuReference/>                            | **SKU reference code:** Displays the reference code of the SKU.                                                                                |
| <vtex.cmc:skuPrice/>                                | **List prices, Computed prices, Installments, and “Save” promotion:** List prices and “Save” promotions are only displayed if the product's computed price is lower than its list price. The best installment plan will be displayed to the customer based on the total price of the order and the interest-free payment options. It does not display information when the product display mode is **SKU list**.                               |
| <vtex.cmc:skuSelection />                           | **SKU selection:** Allows selecting the product variation following the Admin configuration (radio and combo).                                                                                |
| <vtex.cmc:OtherPaymentMethod/>                      | **View other payment methods:** Displays the best payment and installment conditions for a SKU. The SKU must be available in stock for the control to be displayed. This control does not work for categories displayed as "List" in products with multiple SKUs.                                                                                |
| <vtex.cmc:Delivery/>                                | **Availability:** Displays the estimated time it will take for the product to be available, depending on the default logistics route.                                                                                |
| <vtex.cmc:stockKeepingUnitRewardValue/>             | **Loyalty Program Value:** Displays the value of the SKU in the store's loyalty program.                                                                                |
| <vtex.cmc:BuyTogether/>                             | **Buy together:** Displays the SKUs selected in the **Display together** field when adding a SKU.                                                                                |
| <vtex.cmc:ProductDescription/>                      | **Product description:** Displays the information entered in the **Description** field of the product form.                                                                                |
| <vtex.cmc:productDescriptionShort/>                 | **Product short description:** Displays the value entered in the **Additional description** field of the product form.                                                                                |
| <vtex.cmc:productSpecification/>                    | **Product specification:** Additional properties that can be added to your products.                                                                                |
| <vtex.cmc:StockKeepingUnitAttributes/>              | **SKU specification:** Also displays "unstructured attributes" used for seller products.                                                                                |
| <vtex.cmc:stockKeepingUnitMeasures/>                | **Actual SKU dimensions:** Shows the SKU height, width, length, and weight.                                                                                |
| <vtex.cmc:ProductTag/>                              | **Associated tags**                                                                                |
| <vtex.cmc:PageSearch/>                              | **Search within the product page**                                                                                |
| <vtex.cmc:BuyButton/>                               | **Buy button:** Displays the button to add the product to the shopping cart. If the product is out of stock, this control will display the “Notify Me” option, [if enabled](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/set-up-the-avise-me--2VqVifQuf6Co2KG048Yu6e).                                                                                |
| <vtex.cmc:BuyInPage/>                               | **Buy button (Asynchronous):** This control adds the product to the shopping cart asynchronously, without leaving the product page. For this control to work properly, it requires the <vtex.cmc:AmountItemsInCart/> control [as described in this article](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates%23department-category-and-search-page-controls).                                                              |
| <vtex.cmc:stockKeepingUnitAmountAndUnitSelection /> | **Quantity selector with multiplier unit:** Renders a fractional quantity field, considering the unit of measure and unit multiplier set for that SKU. The result is the quantity to be purchased.                                                                                |
| <vtex.cmc:evaluationRate/>                          | **Star ratings given by users:** Displays total ratings from users.                                                                                |
| <vtex.cmc:giftListInsertSku/>                       | **Add product to a list**                                                                                |
| <vtex.cmc:GiftListFormV2/>                          | **Form for creating a list**                                                                                |
| <vtex.cmc:HightLight/>                              | **Collection highlight flag**                                                                                |
| <vtex.cmc:discountHightLight/>                      | **Promotion highlight flag**                                                                                |
| <vtex.cmc:sellerDescription />                      | **Seller description:** Name and image added to the seller of a given product.                                                                                |
| <vtex.cmc:SellerOptions />                          | **Seller options:** Displays the sellers that offer the product, the product price of each seller, and installment options (up to three different prices).                                                                                |
| <vtex.cmc:SalesChannelDropList />                   | **Trade policy list:** Displays a list of available trade policies.                                                                                |
| <vtex:contentPlaceHolder id="ColecaoQVVT"/>         | **”People who looked at this item also looked at” shelf:** It adds a control of type **Related products** in the Legacy CMS Portal that lists products from the same category as the PDP. When editing the element, select QuemViu\_Viu\_Tambem in the **Tipo** field and create a new shelf template. It is a quick and easy way to implement "who looked at this, also looked at" section, offering shoppers purchasing alternatives.        |
| <vtex:contentPlaceHolder id="ColecaoQVCT"/>         | **“People who looked at this item also purchased” shelf:** It adds a control of type **Related products** in the Legacy CMS Portal that lists products from the same category as the PDP. When editing the element, select QuemComprou\_Viu\_Tambem in the **Tipo** field and create a new shelf template. It is a quick and easy way to implement "who looked at this, also purchased" section, offering shoppers purchasing alternatives.    |
| <vtex:contentPlaceHolder id="ColecaoQCCT"/>         | **People who purchased this item also purchased” shelf:** It adds a control of type **Related products** in the Legacy CMS Portal that lists products from the same category as the PDP. When editing the element, select QuemComprou\_Comprou\_Tambem in the **Tipo** field and create a new shelf template. It is a quick and easy way to implement "who purchased this, also purchased" section, offering shoppers purchasing alternatives. |
| <vtex:contentPlaceHolder id="Similares"/>           | **Similar/Related products:** It adds a control of type **Related products** in the Legacy CMS Portal that lists the SKUs configured as similar in the SKU registration. When editing the element, select Similar in the **Tipo** field.                                                                                |
| <vtex:contentPlaceHolder id="Acessorios"/>          | **Accessories:** It adds a control of type **Related products** in the Legacy CMS Portal that lists the SKUs configured as accessories in the SKU registration. When editing the element, select Acessorios in the **Tipo** field.                                                                                |
| <vtex:contentPlaceHolder id="Sugestoes"/>           | **Suggestions:** It adds a control of type **Related products** in the Legacy CMS Portal that lists the SKUs configured as suggestions in the SKU registration. When editing the element, select Sugestao in the **Tipo** field.                                                                                |
| <vtex.cmc:facebookLike/>                            | **Facebook Like**                                                                                |

### RichSnippets controls

The `<vtex.cmc:productRichSnippets />` control adds specific tags for sharing information through social media, such as Google microformats, Facebook Open Graph, and Twitter cards. The testing tools are:

1. [Google Structured Data Testing Tool](https://read.calvincode.net/reader?url=https://www.google.com/webmasters/tools/richsnippets)
2. [Facebook Sharing Debugger](https://read.calvincode.net/reader?url=https://developers.facebook.com/tools/debug/)
3. [Twitter Card Validator](https://read.calvincode.net/reader?url=https://cards-dev.twitter.com/validator)

| Property       | Possible values                     |
| -------------- | ----------------------------------- |
| showGoogle     | { "1", "true", "on", "yes" }        |
| showFacebook   | { "1", "true", "on", "yes" }        |
| Twitter        | @accountname of the Twitter account |
| doNotshowPrice | { "1", "true", "on", "yes" }        |
| googleRate     | { "1", "true", "on", "yes" }        |
| fbAdmins       |                                     |
| fbAppId        |                                     |

| Control                                                                                | Example of use                                                                                |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| <vtex.cmc:productRichSnippets showGoogle="1"/>                                                 | For the product to be indexed on Google, the control needs to be in the <body> tag.                    |
| <vtex.cmc:productRichSnippets showFacebook="1" fbAdmins="\[fbAdmins\]" fbAppId="\[fbAppId\]"/> | For Facebook, the control needs to be in the <head> tag. fbAdmins and fbAppId settings are optional.   |
| <vtex.cmc:productRichSnippets Twitter="\[TwitterAccount\]"/>                                   | For Twitter, the control can be added to <head> or <body> tags. Settings can also be grouped together. |

## Department, category, and search page controls

| Control                               | Description                                                                                |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <vtex.cmc:advancedSearchFilter/>      | **Advanced Search Filter**                                                                                |
| <vtex.cmc:singleDepartmentNavigator/> | **Department menu:** The available attribute is keepCurrentPath. When this attribute is set to true, products will be displayed on the page.                                                                                |
| <vtex.cmc:searchNavigator/>           | **Search menu/filter:** Displays a menu with your store departments and categories (levels 1 and 2). To display the link to the **complete list**, the **Menu** field must be enabled when [creating categories](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/registering-a-category--tutorials%5F206).           |
| <vtex.cmc:miniCart/>                  | **Minicart control:** A shopping cart control used in the top menu of all pages — except Checkout and the order confirmation page. This control displays shopping cart information, such as items, quantities, and prices.                                                                             |
| <vtex.cmc:AmountItemsInCart>          | **Number of items in the shopping cart:** Displays basic information about the shopping cart. This control is required if you use the <vtex.cmc:BuyInPage/> control. For example, you could use it for [KitLook](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/how-to-assemble-a-look-kit--tutorials%5F266) cases. |
| <vtex.cmc:searchResult/>              | Product search results. The attributes of this control are described below.                                                                                |

The `<vtex.cmc:searchResult/>` control attributes are:

| Tag attribute             | Description                                                                  |
| ------------------------- | ---------------------------------------------------------------------------- |
| layout                    | Required attribute. Code of the shelf (template) that will display products. |
| itemCount                 | Required attribute. Number of items per page.                                |
| columnCount               | Required attribute. Number of columns.                                       |
| showUnavailable           | When this attribute is set to true, out-of-stock products will be displayed. |
| selectionMode=”batch-buy” | Optional attribute that allows sorting products in bulk.                     |
| isTrackable               | When this attribute is set to true, this control is trackable.               |
| InternalCampaign          | Audience name of the internal campaign.                                      |
| InternalPart              | Internal _ViewPart_ name.                                                    |

Search results example:

`1

2

<vtex.cmc:searchResult layout="48e223e6-da80-4610-b3d5-4e5cfaf94f13" itemCount="10" columnCount="4" isTrackable="true" InternalCampaign="Search results landing" InternalPart="Search Results" />

`

For more information, read the tutorial [Shelf template controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls).

## Other controls

| Control                        | Description                                                                                |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| <vtex.cmc:orderList/>          | Displays the customer order list in the **Orders** section of **My account** – /account/orders                          |
| <vtex.cmc:accountUserProfile/> | Displays the customer information in **My account** – /account                                                          |
| <vtex.cmc:accountAddress/>     | Displays the customer addresses on the **My account** page – /account                                                   |
| <vtex.cmc:sellerInfo />        | Displays the seller information on the platform and should be used on the seller detail page in the seller-info folder. |

## Deprecated controls

| Control                                                              | Description                                                                                | Page         |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| <vtex.cmc:productPageTitle/>                                         | DEPRECATED **Product title**                                                                                | Product page |
| <vtex.cmc:stockKeepingUnitSelection/>                                | DEPRECATED **SKU selection**. Use <vtex.cmc:skuSelection/> instead.                                                                                | Product page |
| <vtex.cmc:skuRichSelection changeImage="1"/>                         | DEPRECATED **SKU checkbox selection**                                                                                | Product page |
| <vtex.cmc:shippingValue/>                                            | DEPRECATED **Calculate shipping cost and delivery time frame**. This control has a [known issue](https://read.calvincode.net/reader?url=https://help.vtex.com/en/known-issues/a-viewpart-shippingvalue-nao-exibe-prazos-em-horas-corretamente--5hvl9eGxPLZAuNcFAFc9Vb%23). | Product page |
| <vtex.cmc:stockKeepingUnitService/>                                  | DEPRECATED **SKU services**                                                                                | Product page |
| <vtex.cmc:StockKeepingUnitPriceHistory Months="6" Percentile="100"/> | DEPRECATED **Price history**                                                                                | Product page |
| <vtex.cmc:evaluationRate/>                                           | DEPRECATED **Consumer rating (stars)**. Previously, this displayed the average star rating from customers.                                                                                | Product page |
| <vtex.cmc:UserReview/>                                               | DEPRECATED **Ratings and comments**. This previously displayed an option to rate products, a form to add a review, rating results, and added reviews.                                                                             | Product page |
| <vtex.cmc:welcomeMessage/>                                           | DEPRECATED **User login**. This created the IPI cookie used by the <vtex.cmc:UserReview/> control. Without it, login was required in a loop when trying to add a review.                                                          | Product page |

Contributors

5

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F25390429%3Fv%3D4%26w=64%26q=75)](https://github.com/karenkrieger)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F106821144%3Fv%3D4%26w=64%26q=75)](https://github.com/GeorgeLimaDev)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F67270558%3Fv%3D4%26w=64%26q=75)](https://github.com/mariana-caetano)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/legacy-cms/list-of-controls-for-templates.md)

[Can I order my product as I want?« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates//docs/guides/can-i-order-my-product-as-i-want)[Setting up the zoomNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates//docs/guides/setting-up-the-zoom)

Contributors

5

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F25390429%3Fv%3D4%26w=64%26q=75)](https://github.com/karenkrieger)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F106821144%3Fv%3D4%26w=64%26q=75)](https://github.com/GeorgeLimaDev)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F67270558%3Fv%3D4%26w=64%26q=75)](https://github.com/mariana-caetano)

ON THIS PAGE

[General controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23general-controls)

[Product page controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23product-page-controls)

[RichSnippets controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23richsnippets-controls)

[Department, category, and search page controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23department-category-and-search-page-controls)

[Other controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23other-controls)

[Deprecated controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23deprecated-controls)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/legacy-cms/list-of-controls-for-templates.md)

Copy page

On this page

ON THIS PAGE

[General controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23general-controls)

[Product page controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23product-page-controls)

[RichSnippets controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23richsnippets-controls)

[Department, category, and search page controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23department-category-and-search-page-controls)

[Other controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23other-controls)

[Deprecated controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/list-of-controls-for-templates/docs/guides/list-of-controls-for-templates%23deprecated-controls)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides how to use and create clients on vtex io in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-service)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/calling-commerce-apis-on-vtex-io)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-clients)

[Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients)

[Connecting to VTEX Core Commerce APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/how-to-connect-with-vtex-core-commerce-apis-using-vtex-io)

[Using Clients in Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/using-node-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-service)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/calling-commerce-apis-on-vtex-io)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-clients)

[Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients)

[Connecting to VTEX Core Commerce APIs](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/how-to-connect-with-vtex-core-commerce-apis-using-vtex-io)

[Using Clients in Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/using-node-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/app-development)

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/app-development-guides)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-clients)

[Developing custom Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients)

Developing Clients

Learn how to develop custom Clients for seamless communication with other services.

If you need to integrate your VTEX IO app with external services that aren't covered by [VTEX IO's native Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-clients), creating custom Clients can be a powerful solution. Custom Clients extend the functionality of VTEX IO Client types, offering benefits like caching and versioning. This guide will walk you through the process of creating custom Clients for your VTEX IO apps.

> Note that direct communication with APIs is generally discouraged in favor of implementing a dedicated Client. By creating custom Clients, you can extend the capabilities of your VTEX IO applications, enabling seamless integration with a wide range of services.

The diagram below illustrates how an app works with a Client to an external service:

Requester / eventIO appExternalserviceRequest to IO app / event listened by IO appRequest with  custom ClientResponse of  external service\[If requester\]  Response of IO appRequester / eventIO appExternalservice

As you develop your custom Client, you will define methods within it. These Client methods are functions responsible for handling the logic needed to execute specific actions. They facilitate interactions with services and APIs, managing requests and responses effectively.

Once you've created your custom Client, you can seamlessly integrate it into your VTEX IO app to execute the implemented methods. While you have the flexibility to incorporate data-handling logic within your Client's methods (e.g., field mapping or data filtering), it's essential to keep the core responsibilities of the Client well-organized.

## Before you begin

Before diving into Client development, make sure you have the following prerequisites in place:

* **VTEX IO development workspace:** Ensure you have a VTEX IO development workspace set up. For more information, refer to [Creating a Development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-development-workspace).
* **TypeScript Familiarity:** This guide assumes you have a basic understanding of TypeScript, as we'll be using the `node` [Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-builders) to develop with TypeScript. For more information, refer to [TypeScript's official documentation](https://read.calvincode.net/reader?url=https://www.typescriptlang.org/docs/).
* **Understanding of Clients:** Clients play a crucial role in facilitating interactions between your application and both external and internal services. For more information, refer to [Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-clients).

## Instructions

In this guide, we will create a custom Client example for communicating with GitHub APIs. We'll implement the following methods within our Client:

* `getRepo`: Fetches a GitHub repository given the owner and repository name.
* `getUser`: Retrieves GitHub user data based on a specified GitHub username.
* `createTag`: Creates a new tag on GitHub, taking into account the repository owner, repository, and tag data.
* `searchRepos`: Searches for GitHub repositories using a specified query.

### Step 1 - Setting up your VTEX IO app

1. Start a new VTEX IO app using the `node` builder and open the project using your preferred code editor.
2. Open a terminal and navigate to the `node` folder of your project.
`1
cd node
`
3. Install the `@vtex/api` and `@octokit/rest` packages by running the following command:
`1
yarn add @vtex/api @octokit/rest
`
4. Open the app's `manifest.json` file and add the necessary [Policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-policies). Policies are a set of permissions granted to an app, allowing or forbidding it to execute a given set of actions, such as making requests to an external resource. For this example, we will use the `outbound-access` policy to communicate with GitHub APIs (`api.github.com`).
manifest.json
`1
"policies": [
2
 {
3
 "name": "outbound-access",
4
 "attrs": {
5
 "host": "api.github.com",
6
 "path": "*"
7
 }
8
 },
9
]
`
> Note that incorrect policies may result in request blocking.

### Step 2 - Creating a custom Client

1. Create a folder named `clients` inside the `node` directory.
2. Create a TypeScript file for your Client in the `node/clients` directory. Choose a name that easily identifies your Client (e.g., `github.ts`).
3. Implement the TypeScript class that extends the appropriate [Client type](#client-types) from `@vtex/api`. In this example, we will create the `GithubClient`. Also, since we are communicating with GitHub's external APIs, we will use `ExternalClient`.
4. Use [InstanceOptions](#instanceoptions) as needed, configuring options such as authentication, timeout, caching, and more based on your requirements.

node/clients/github.ts

`1

import type { IOContext, InstanceOptions } from '@vtex/api'

2

import { ExternalClient } from '@vtex/api'

3

4

export default class GithubClient extends ExternalClient {

5

 constructor(context: IOContext, options?: InstanceOptions) {

6

 super('http://api.github.com', context, {

7

 ...options,

8

 retries: 2,

9

 headers: {

10

 Accept: 'application/vnd.github.machine-man-preview+json',

11

 'x-vtex-use-https': 'true'

12

 }

13

 });

14

 }

15

16

 // Add the Client-related methods here

17

}

`

Ensure to export the Client from its module, either [default or named export](https://read.calvincode.net/reader?url=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export).

### Step 3 - Implementing Client methods

Within your Client TypeScript file, implement the methods for your Client. You can leverage the methods provided by the [HttpClient](#httpclient-methods) to build your own methods. For example:

node/clients/github.ts

`` 1

import type { RestEndpointMethodTypes } from '@octokit/rest'

2

3

...

4

5

 public getRepo({ owner, repo }: GitRepo, token?: string) {

6

 return this.http.get<RestEndpointMethodTypes['repos']['get']['response']>(

7

 this.routes.repo({ owner, repo }),

8

 {

9

 metric: 'git-repo-get',

10

 headers: {

11

 ...this.options?.headers,

12

 Accept: 'application/vnd.github.nebula-preview+json',

13

 ...(token && { Authorization: `token ${token}` }),

14

 },

15

 }

16

 )

17

 }

 ``

Below we have the complete code example:

VTEX API core types:

* `IOContext`: Contains the VTEX IO context data, such as account, workspace, locale, authentication token, etc.
* [InstanceOptions](#instanceoptions): The options for configuring your `HttpClient` instance.
* `ExternalClient`: The base Client class for communicating with external APIs.

Type of the base Client that the custom Client extends from. Used to connect with external APIs.

A variable to store a map of routes for each method implemented in the Client. This structure is not mandatory, but it makes the code more readable when calling the `HttpClient` methods.

The `baseUrl` argument in `super` must be a URL starting with `http://`. For a secure connection, set the header `'x-vtex-use-https'` to `'true'`. This header changes the request to HTTPS when it leaves the VTEX infrastructure.

Configuration options for each request of this Client. It extends `AxiosRequestConfig`, adding some IO-specific options. In this example, we are setting the number of retries, the `Accept` header to indicate the desired format, and the `x-vtex-use-https` header to force the use of HTTPS.

The `metric` parameter gives a name to identify each HTTP call for analytics purposes.

The `getRaw` method retrieves additional information about the response, such as headers. The `get` method retrieves only the response body.

The query parameters are passed using this format, resulting in `?q={{query}}` being appended to the request's URL.

node/github.ts

`` 1

import type { IOContext, InstanceOptions } from '@vtex/api'

2

import { ExternalClient } from '@vtex/api'

3

import type { RestEndpointMethodTypes } from '@octokit/rest'

4

5

interface GitRepo {

6

 owner: string

7

 repo: string

8

}

9

10

export default class GithubClient extends ExternalClient {

11

 private routes = {

12

 repo: ({ owner, repo }: GitRepo) => `/repos/${owner}/${repo}`,

13

 user: ({ username }: { username: string }) => `/users/${username}`,

14

 tags: ({ owner, repo }: GitRepo) => `/repos/${owner}/${repo}/git/tags`,

15

 searchRepos: () => '/search/repositories',

16

 }

17

18

 constructor(context: IOContext, options?: InstanceOptions) {

19

 super('http://api.github.com', context, {

20

 ...options,

21

 retries: 2,

22

 headers: {

23

 Accept: 'application/vnd.github.machine-man-preview+json',

24

 'x-vtex-use-https': 'true',

25

 },

26

 })

27

 }

28

29

 public getRepo({ owner, repo }: GitRepo, token?: string) {

30

 return this.http.get<RestEndpointMethodTypes['repos']['get']['response']>(

31

 this.routes.repo({ owner, repo }),

32

 {

33

 metric: 'git-repo-get',

34

 headers: {

35

 ...this.options?.headers,

36

 Accept: 'application/vnd.github.nebula-preview+json',

37

 ...(token && { Authorization: `token ${token}` }),

38

 },

39

 }

40

 )

41

 }

42

43

 public async getUser({ username }: { username: string }) {

44

 const response = await this.http.getRaw<

45

 RestEndpointMethodTypes['users']['getByUsername']['response']

46

 >(this.routes.user({ username }), { metric: 'git-user-get' })

47

48

 return response.data

49

 }

50

51

 public createTag(

52

 {

53

 owner,

54

 repo,

55

 ...tagData

56

 }: {

57

 owner: string

58

 repo: string

59

 } & RestEndpointMethodTypes['git']['createTag']['parameters'],

60

 token?: string

61

 ) {

62

 console.info('Tag data:', tagData)

63

64

 return this.http.post<RestEndpointMethodTypes['git']['createTag']>(

65

 this.routes.tags({ owner, repo }),

66

 tagData,

67

 {

68

 metric: 'git-create-tag',

69

 headers: {

70

 ...this.options?.headers,

71

 ...(token && { Authorization: `token ${token}` })

72

 },

73

 }

74

 )

75

 }

76

77

 public searchRepos({ query }: { query: string }) {

78

 return this.http.get<

79

 RestEndpointMethodTypes['search']['repos']['response']

80

 >(this.routes.searchRepos(), {

81

 metric: 'git-search-repos',

82

 params: { q: query },

83

 })

84

 }

85

}

 ``

### Step 4 - Exporting custom clients

Now that you've created your custom Client, you need to organize and export it for use in your VTEX IO service. Follow these steps:

1. Create an `index.ts` file in the `node/clients` folder.
2. Inside the `index.ts` file, import the custom Client you created in the previous step. For example:
`1
import GithubClient from "./github.ts";
`
3. Define a class called `Clients` that extends `IOClients`. This class is used to organize and configure your custom Clients. Within the Clients class, declare a `get` property for each of your custom Clients. This property allows you to access a specific Client by name. In our example, we've created a Client named `github` that uses the `GithubClient` class.
`1
import { IOClients } from "@vtex/api";
2
import GithubClient from "./github.ts";
3

4
export class Clients extends IOClients {
5
 public get github() {
6
 return this.getOrSet("github", GithubClient);
7
 }
8
}
`

Now that you have developed and exported your custom Client to communicate with the desired service, your Clients can be accessed and used within your VTEX IO service to perform various tasks, such as interacting with external APIs like GitHub. Learn how to use Clients effectively in the [Using Node Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-node-clients) guide.

## Client types

The [@vtex/api](https://read.calvincode.net/reader?url=https://github.com/vtex/node-vtex-api/) package provides a structured way to create Clients.

| Type             | Use case                                                         |
| ---------------- | ---------------------------------------------------------------- |
| AppClient        | Communication with other IO Services via HTTP calls.             |
| AppGraphQLClient | Communication with other IO GraphQL services.                    |
| ExternalClient   | Communication with external APIs.                                |
| JanusClient      | Communication with VTEX Core Commerce APIs through Janus Router. |
| InfraClient      | Communication with VTEX IO Infra services.                       |

Refer to the diagram below to better understand the relationship between Client types.

IOClient

http: HttpClient

constructor(context,options)

HttpClient

cacheableType: CacheType

logger: Logger

runMiddlewares: ComposedMiddleware

delete

get

getRaw

getWithBody

name: string

post

postRaw

put

putRaw

getConfig:(url: string, config?: RequestConfig)

request:(config: RequestConfig) : => Promise

getBuffer:(url: string, config?: RequestConfig) : => Promise<>

getStream:(url: string, config?: RequestConfig) : => Promise

head:(url: string, config?: RequestConfig) : => Promise>

GraphQLClient

mutate

query

constructor(http:HttpClient)

IOGraphQLClient

graphql: GraphQLClient

constructor(context,options)

AppGraphQLClient

constructor(app,context,options)

InfraClient

constructor(app, context, options, isRoot)

ExternalClient

constructor(baseURL,context,options)

JanusClient

constructor(context,options,environment)

AppClient

constructor(app,context,options)

Note that `context` is of type `IOContext` and `options` is of type [InstanceOptions](#instanceoptions).

## `InstanceOptions`

The `InstanceOptions` table below provides a detailed description of the available options for configuring your `HttpClient` instance:

| Option                        | Description                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| authType                      | Specifies the authentication type.                                                  |
| timeout                       | Sets the request timeout duration in milliseconds.                                  |
| memoryCache                   | Configures a memory cache layer for caching data.                                   |
| diskCache                     | Configures a disk cache layer for caching data.                                     |
| baseURL                       | Defines the base URL for making requests.                                           |
| retries                       | Specifies the number of times a request should be retried in case of failure.       |
| exponentialTimeoutCoefficient | Configures the coefficient for exponential timeout backoff strategy.                |
| initialBackoffDelay           | Sets the initial delay before starting exponential backoff retries in milliseconds. |
| exponentialBackoffCoefficient | Configures the coefficient for exponential backoff retries.                         |
| metrics                       | Specifies an object for accumulating metrics related to requests.                   |
| concurrency                   | Defines the maximum number of concurrent requests.                                  |
| headers                       | Sets default headers to be sent with every request.                                 |
| params                        | Sets default query string parameters to be sent with every request.                 |
| middlewares                   | Configures an array of middleware functions for request processing.                 |
| verbose                       | Enables or disables verbose logging for requests and responses.                     |
| name                          | Defines a custom name for the instance.                                             |
| serverTimings                 | Sets server timings for measuring request and response times.                       |
| httpsAgent                    | Configures the HTTPS agent for making requests over SSL/TLS.                        |

## `HttpClient` methods

Below is a table outlining the methods available in the `HttpClient` class:

| Method                                                       | Description                                                                                |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| get(url: string, config?: RequestConfig)                     | Sends an HTTP GET request. Returns only the response body.                                               |
| getRaw(url: string, config?: RequestConfig)                  | Sends an HTTP GET request. Returns all the response data.                                                |
| getWithBody(url: string, data?: any, config?: RequestConfig) | Sends an HTTP GET request with a request body.                                                           |
| getBuffer(url: string, config?: RequestConfig)               | Sends an HTTP GET request and resolves with the response data as a buffer along with the headers.        |
| getStream(url: string, config?: RequestConfig)               | Sends an HTTP GET request and resolves with the response as a readable stream (of type IncomingMessage). |
| put(url: string, data?: any, config?: RequestConfig)         | Sends an HTTP PUT request. Returns only the response body.                                               |
| putRaw(url: string, data?: any, config?: RequestConfig)      | Sends an HTTP PUT request. Returns all the response data.                                                |
| post(url: string, data?: any, config?: RequestConfig)        | Sends an HTTP POST request. Returns only the response body.                                              |
| postRaw(url: string, data?: any, config?: RequestConfig)     | Sends an HTTP POST request. Returns all the response data.                                               |
| patch(url: string, data?: any, config?: RequestConfig)       | Sends an HTTP PATCH request. Returns only the response body.                                             |
| head(url: string, config?: RequestConfig)                    | Sends an HTTP HEAD request and resolves when the request is complete.                                    |
| delete(url: string, config?: RequestConfig)                  | Sends an HTTP DELETE request.                                                                            |

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7026595%3Fv%3D4%26w=64%26q=75)](https://github.com/henriquessb)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Getting-Started/back-end-development-guides/vtex-io-documentation-how-to-create-and-use-clients.mdx)

[Clients« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io//docs/guides/vtex-io-documentation-clients)[Connecting to VTEX Core Commerce APIsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io//docs/guides/how-to-connect-with-vtex-core-commerce-apis-using-vtex-io)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7026595%3Fv%3D4%26w=64%26q=75)](https://github.com/henriquessb)

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23instructions)

[Step 1 - Setting up your VTEX IO app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-1-setting-up-your-vtex-io-app)[Step 2 - Creating a custom Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-2-creating-a-custom-client)[Step 3 - Implementing Client methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-3-implementing-client-methods)[Step 4 - Exporting custom clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-4-exporting-custom-clients)

[Client types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23client-types)

[InstanceOptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23instanceoptions)

[HttpClient methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23httpclient-methods)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Getting-Started/back-end-development-guides/vtex-io-documentation-how-to-create-and-use-clients.mdx)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23instructions)

[Step 1 - Setting up your VTEX IO app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-1-setting-up-your-vtex-io-app)[Step 2 - Creating a custom Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-2-creating-a-custom-client)[Step 3 - Implementing Client methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-3-implementing-client-methods)[Step 4 - Exporting custom clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23step-4-exporting-custom-clients)

[Client types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23client-types)

[InstanceOptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23instanceoptions)

[HttpClient methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-use-and-create-clients-on-vtex-io/docs/guides/vtex-io-documentation-how-to-create-and-use-clients%23httpclient-methods)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] How do I use the VTEX badges 3.10.3 README pt app? Provide documentation and configuration details.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/guides/vtex-io-deprecated-apps)

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/vtex-io-apps)

Badges

[vtex.badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges)

Version: 3.10.3

Latest version: 3.10.3

O aplicativo de Badges tem como objetivo adicionar Badges de conteúdo em seu ecommerce. Há uma aplicação no admin em que poderão ser adicionadas, editadas e removidas as badges e há também um componente para frente de loja em que poderão ser acrescentadas as badges cadastradas no tema da sua store.

## Instalando

### O ADMIN

Para instalar o aplicativo no admin e, assim, gerenciar suas badges, deve-se entrar em seu terminal, logar no workspace e digitar o comando:

`1

 vtex install vtex.badges@3.x

`

### A Store

Para disponibilizar o componente em sua loja, é necessário adicionar nas "peerDependencies" do manifest o seguinte código:

`1

 "vtex.badges": "3.x"

`

Em seguida, já é possível adicionar o componente de badges em sua loja.

## O funcionamento

### No ADMIN

Após instalar o aplicativo em sua loja, já estará disponível em seu ambiente ADMIN o aplicativo de Gerenciamento de Badges. Para utilizá-lo, basta acessar a barra lateral em "OUTROS", a qual deve conter o aplicativo "Gerenciamento de Badges". Clicando no aplicativo, deverá visualizar a seguinte página:

![Captura de Tela 2021-10-22 às 11 21 22](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/80836180/138470628-9936a747-96ec-40a3-8ab5-d57115654e2d.png)

Nessa página é possível criar uma nova badge

* Adicionando o nome da badges
* Adicionando o conteúdo da badge (como imagem, texto ou html)
* Adicionando a prioridade da badges (sendo 1 a prioridade máxima e 5 a menor)
* Adicionando uma regra de ativação

Um exemplo de como pode-se ser preenchido o formulário que está contido abaixo.

![Captura de Tela 2021-10-22 às 11 02 41](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/80836180/138469242-868ff4a2-e808-4371-8f33-099e39743877.png)

Nesse mesmo gerenciamento pode-se editar ou excluir uma badge em questão, basta-se mudar a aba do formulário de "Adicionar Badge" para "Editar Badges" e ser clicado no botão de "LineActions", como pode-se ser visto na imagem abaixo:

![Captura de Tela 2021-12-03 às 10 22 10](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/80836180/144609583-c6583e99-79d6-4224-b267-07c6c3f54767.png)

Também é importante acrescentar que para o perfeito funcionamento do aplicativo, no campo de regra de ativação deve haver pelo menos uma condição que seja utilizado o verbo "É". Desta forma, não deve haver um badge cuja regra de ativação seja **unicamente** "NÃO É"

### Em Meus Aplicativos

Para aprimorar a busca pelas badges, é possível selecionar quais campos você quer que sejam filtradas a busca por elas. Isso permite que a busca no Banco de Dado seja mais simples e mais eficiente na hora de retornar as badges para seu site. Para configura basta entrar na área de Meus Aplicativos. Em seguida escolher   **App Badges**  e selecionar quais campos você deseja que a busca seja relacionada.

![Captura de Tela 2022-11-22 às 13 50 50](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/80836180/203373595-aef6bf9b-de00-43a5-b2fd-0636b97c2fb5.png)

Vale lembrar que por default todos os campos são utilizados como filtro

### Na Store

Agora com as badges cadastradas, é possível adiciona-las em sua loja. Para o correto funcionamento das mesmas é necessário que o componente das badges seja aderida dentro de uma página de produto (store.product) ou dentro de um product-summary. O exemplo abaixo demonstra como colocar uma badges na página de produto.

`1

 "store.product": {

2

 "children": [

3

+ "store-badges",

4

 "stack-layout",

5

 "breadcrumb",

6

 "flex-layout.row#main",

7

 "condition-layout.product"

8

 ]

9

 },

10

11

+ "store-badges":{

12

+ "props": {

13

+ "numberOfBadges": 1,

14

+ "text":{

15

+ "font": "t-heading-5",

16

+ "textColor": "blue",

17

+ "textAlignment": "CENTER",

18

+ "textPosition": "CENTER",

19

+ "htmlId": "teste1"

20

+ },

21

+ "image":{

22

+ "blockClass": "container",

23

+ "height": 500,

24

+ "width": 500,

25

+ "minWidth": 25,

26

+ "minHeight": 25,

27

+ "alt": "teste",

28

+ "title": "title",

29

+ "preload": true

30

+ }

31

+ }

32

+ }

`

### `store-badges` props

| Nome da Prop   | Tipo   | Descrição                                                                                |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| numberOfBadges | number | Define quantas badges serão renderizadas                                                                                |
| text           | array  | Contém definições de valores que serão usados quando se renderiza uma badge de texto. Saiba mais sobre essas props no <https://github.com/vtex-apps/rich-text>    |
| image          | array  | Contém definições de valores que serão usados quando se renderiza uma badge de imagem. Saiba mais sobre essas props no <https://github.com/vtex-apps/store-image> |

### O resultado final

Com todas as etapas concluídas já é possível conferir o resultado final em sua store. A ordem das badges é definida de acordo com a prioridade escolhida na hora de cadastrá-las. O exemplo abaixo mostra como ficaria a uma store que foi seguido o passo a passo desse tutorial.

![Captura de Tela 2021-12-03 às 10 16 28](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/80836180/144608846-590d4d12-4924-479c-976b-4573a6b6bacc.png)

**Upcoming documentation:**

* [Feature/test back](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/badges/pull/17)

See also

[Vtex.badgesVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges)[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Instalando](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23instalando)

[O ADMIN](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23o-admin)[A Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23a-store)

[O funcionamento](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23o-funcionamento)

[No ADMIN](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23no-admin)[Em Meus Aplicativos](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23em-meus-aplicativos)[Na Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23na-store)[store-badges props](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23store-badges-props)[O resultado final](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.badges@3.10.3/README_pt/docs/apps/vtex.badges@3.10.3/README%5Fpt%23o-resultado-final)

Was this helpful?

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)