[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 vtex condition layout 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/vtex-condition-layout/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/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/vtex-condition-layout/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/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/vtex-condition-layout/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/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/vtex-condition-layout/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.b2b-suite)

---

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

---

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

[Condition Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout)

[Disclosure Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.disclosure-layout)

[Flex Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.flex-layout)

[Modal Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.modal-layout)

[Overlay Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.overlay-layout)

[Responsive Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.responsive-layout)

[Slider Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.slider-layout)

[Stack Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.stack-layout)

[Sticky Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.sticky-layout)

[Tab Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.tab-layout)

---

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

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.my-account)

---

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

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.b2b-suite)

---

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

---

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

[Condition Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout)

[Disclosure Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.disclosure-layout)

[Flex Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.flex-layout)

[Modal Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.modal-layout)

[Overlay Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.overlay-layout)

[Responsive Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.responsive-layout)

[Slider Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.slider-layout)

[Stack Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.stack-layout)

[Sticky Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.sticky-layout)

[Tab Layout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.tab-layout)

---

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

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.my-account)

---

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

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/vtex-io-apps)

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

Condition Layout

Official extension

Version: 2.8.2

Latest version: 2.8.2

[![{"base64":"  ","img":{"width":110,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square"}}](https://read.calvincode.net/reader?url=https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)

The Condition Layout app renders a component in your store when predefined conditions are met.

![{"base64":"  ","img":{"width":742,"height":1504,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":871202,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-condition-layout-0.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-condition-layout-0.gif)

## Configuration

### Step 1 - Adding the Condition Layout app to your theme dependencies

In the `manifest.json` file of your theme, add the Condition Layout app as a dependency:

`1

 "dependencies": {

2

+ "vtex.condition-layout": "2.x"

3

 }

`

You can now use all blocks exported by the `condition-layout` app. See the full list below:

| Block name                     | Description                                                                                |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| condition-layout.product       | Defines the condition logic in the product context and the children blocks that will be rendered when the predefined conditions are met.                     |
| condition-layout.binding       | Defines the condition logic in the current binding and the children blocks that will be rendered when the predefined conditions are met.                     |
| condition-layout.category      | Defines the condition logic on the current category or department page and the children blocks that will be rendered when the predefined conditions are met. |
| condition-layout.telemarketing | Defines the condition logic in the user role (telemarketing) and the children blocks that will be rendered when the predefined conditions are met.           |

### Step 2 - Adding the `condition-layout.product` block to your theme templates

In the product theme template, add the `condition-layout.product` block as a child. For example:

`1

{

2

 "store.product": {

3

 "children": ["condition-layout.product"]

4

 },

`

Or the `condition-layout.binding` block. For example:

`1

{

2

 "store.product": {

3

 "children": ["condition-layout.binding"]

4

 }

5

}

`

Or the `condition-layout.category` block. For example:

`1

{

2

 "store.search#my-category-page": {

3

 "children": ["condition-layout.category"]

4

 }

5

}

`

> Never use `condition-layout` directly. Always use it with a context variant, such as `condition-layout.product`.

### Step 3 - Defining the desired conditions

Now it is time to configure the `condition-layout.product` block!

**Use the block props to define your layout condition**. You can also declare blocks of your choice as children of `condition-layout.product`. These children blocks will be rendered if the condition is met.

For example:

`1

{

2

 "store.product": {

3

 "children": ["condition-layout.product#cond1"]

4

 },

5

 "condition-layout.product#cond1": {

6

+ "props": {

7

+ "conditions": [

8

+ {

9

+ "subject": "productId",

10

+ "arguments": {

11

+ "id": "12"

12

+ }

13

+ }

14

+ ]

15

+ "Then": "flex-layout.row#custom-pdp-layout-12",

16

+ "Else": "flex-layout.row#default"

17

+ }

18

+ }

`

Or for `condition-layout.binding`:

`1

{

2

 "store.product": {

3

 "children": ["condition-layout.binding#cond42"]

4

 },

5

 "condition-layout.binding#cond42": {

6

+ "props": {

7

+ "conditions": [

8

+ {

9

+ "subject": "bindingId",

10

+ "arguments": {

11

+ "id": "13fb71d0-binding-code-here-87h9c28h9013"

12

+ }

13

+ }

14

+ ]

15

+ "Then": "flex-layout.row#just-for-this-binding",

16

+ "Else": "flex-layout.row#for-other-bindings"

17

+ }

18

+ }

`

Or for `condition-layout.category`:

`1

{

2

 "store.product": {

3

 "children": ["condition-layout.category#cond42"]

4

 },

5

 "condition-layout.category#cond42": {

6

+ "props": {

7

+ "conditions": [

8

+ {

9

+ "subject": "department",

10

+ "arguments": {

11

+ "ids": ["1", "42"]

12

+ }

13

+ }

14

+ {

15

+ "subject": "category",

16

+ "arguments": {

17

+ "ids": ["301", "304"]

18

+ }

19

+ }

20

+ ]

21

+ "matchType": "any",

22

+ "Then": "flex-layout.row#just-for-this-category-or-department",

23

+ "Else": "flex-layout.row#for-other-category-or-department"

24

+ }

25

+ }

`

Or for `condition-layout.telemarketing`:

`1

{

2

 "store.product": {

3

 "children": ["condition-layout.telemarketing#show-block"]

4

 },

5

 "condition-layout.telemarketing#show-block": {

6

+ "props": {

7

+ "conditions": [

8

+ {

9

+ "subject": "impersonable",

10

+ "arguments": {

11

+ "value": true

12

+ }

13

+ }

14

+ ]

15

+ "Then": "flex-layout.row#just-for-telemarketers",

16

+ "Else": "flex-layout.row#for-other-user-roles"

17

+ }

18

+ }

`

> In the example above, whenever users interact with a product whose ID is equal to 12, the `flex-layout.row#custom-pdp-layout-12` block is rendered. If users interact with a product whose ID is not equal to 12, the rendered block is `flex-layout.row#default`.

| Prop name  | Type   | Description                                                                                | Default value |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| conditions | object | List of desired conditions.                                                                                | undefined     |
| matchType  | enum   | Layout rendering criteria. Possible values are: all (all conditions must be met to render the layout), any (at least one of the conditions must be met to render the layout), or none (no conditions must be met to render the layout). | all           |
| Then       | block  | Name of the block to be rendered if the conditions are met. If no value is defined, the blocks declared as children of condition-layout.product will be rendered instead.                                                               | undefined     |
| Else       | block  | Name of the block to be rendered if the conditions are not met.                                                                                | undefined     |

* **`conditions` object:**

| Prop name | Type    | Description                                                                                | Default value |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| subject   | string  | Defines, based on the product context where the block is declared, which information is needed from the UI to validate the value chosen in the object prop. See below the possible values for this prop.                   | undefined     |
| arguments | object  | Defines the condition parameters. Note that the value of this prop varies depending on the value set for the subject prop. See below the table with the possible values for the subject prop and their expected arguments. | undefined     |
| toBe      | boolean | Determines whether the data fetched in the subject prop must meet the predefined conditions to render the new layout (true) or not (false).                                                                                | true          |

Possible values for `subject` prop of the `condition-layout.product` block:

| Subject                  | Description                                                                                | Arguments                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| productId                | Product IDs currently displayed on the UI.                                                                               | { id: string }                                                                                |
| categoryId               | Category IDs currently displayed on the UI.                                                                              | { id: string }                                                                                |
| brandId                  | Brand IDs currently displayed on the UI.                                                                                | { id: string }                                                                                |
| selectedItemId           | ID of the item currently selected by the user.                                                                           | { id: string }                                                                                |
| productClusters          | List of product clusters currently displayed on the UI.                                                                  | { id: string }                                                                                |
| categoryTree             | List of categories currently displayed on the UI. **Note:** Only available on the Product Detail Page.                   | { id: string }                                                                                |
| specificationProperties  | List of product specifications currently displayed on the UI.                                                            | { name: string, value: string }. Note: value is an optional prop. If omitted, only the specification name (name) will be checked. |
| areAllVariationsSelected | Determines whether all product variations currently available on the UI were selected by the user (true) or not (false). | No arguments are expected.                                                                                |
| isProductAvailable       | Determines whether the product is available (true) or not (false).                                                       | No arguments are expected.                                                                                |
| hasMoreSellersThan       | Determines whether the number of sellers for a product is greater than the argument passed.                              | { quantity: number }                                                                                |
| hasBestPrice             | Whether the product is being given a discount on its list price.                                                         | { value: boolean } or no arguments.                                                                                |
| sellerId                 | Whether any of the sellers of the product are included in the list of IDs passed.                                        | { ids: string\[\] }                                                                                |

Possible values for the `subject` prop of the `condition-layout.binding` block:

| Subject   | Description                      | Arguments      |
| --------- | -------------------------------- | -------------- |
| bindingId | ID of the desired store binding. | { id: string } |

Possible values for the `subject` prop of the `condition-layout.category` block:

| Subject    | Description                                   | Arguments           |
| ---------- | --------------------------------------------- | ------------------- |
| category   | Category IDs currently displayed on the UI.   | { ids: string\[\] } |
| department | Department IDs currently displayed on the UI. | { ids: string\[\] } |

Possible values for the `subject` prop of the `condition-layout.telemarketing` block:

| Subject      | Description                         | Arguments          |
| ------------ | ----------------------------------- | ------------------ |
| impersonable | Value of the impersonation setting. | { value: boolean } |

## App behavior

The `condition-layout.product` block mainly uses the `matchType` and `conditions` props to respectively set the criteria and the conditions that blocks must meet to be rendered.

The `conditions` prop does not rely on any automatic grammar to define the desired conditions. Instead, it relies on its two props, namely `subject` and `arguments`, which together define which condition must be met by using an underlying data validation method (with specific arguments) based on the UI behavior.

Lastly, the `matchType` prop decides the necessary number of valid conditions for the layout rendering.

## Customization

The Condition Layout merely establishes a logic to render other blocks. Therefore, the app does not have its own CSS handles for customization.

Instead, you should use the handles of the child blocks.

[Layout Apps« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/guides/layout-apps)[Disclosure LayoutNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.disclosure-layout)

See also

[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)[V1 DOCVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout@2.8.2/v1-DOC)[MIGRATION GUIDEVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout@2.8.2/MIGRATION-GUIDE)

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout%23configuration)

[Step 1 - Adding the Condition Layout app to your theme dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout%23step-1-adding-the-condition-layout-app-to-your-theme-dependencies)[Step 2 - Adding the condition-layout.product block to your theme templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout%23step-2-adding-the-condition-layoutproduct-block-to-your-theme-templates)[Step 3 - Defining the desired conditions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout%23step-3-defining-the-desired-conditions)

[App behavior](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout%23app-behavior)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-condition-layout/docs/apps/vtex.condition-layout%23customization)

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=)


[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 vtex io documentation installing apps in live stores best practices 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/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/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/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/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/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/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/vtex-io-documentation-installing-apps-in-live-stores-best-practices/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-using-advanced-layouts)

[Working with Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-configuring-analytics-google-tag-manager)

[Setting up cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-setting-up-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-managing-performance)

[Improving store accessibility with semantic HTML migration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-updating-live-stores)

[Migrating CMS settings after a Store Theme major update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update)

[Installing apps on live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-using-advanced-layouts)

[Working with Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-configuring-analytics-google-tag-manager)

[Setting up cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-setting-up-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-managing-performance)

[Improving store accessibility with semantic HTML migration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-updating-live-stores)

[Migrating CMS settings after a Store Theme major update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update)

[Installing apps on live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/storefront-best-practices)

---

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/storefront-development)

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/store-framework-updating-live-stores)

[Installing apps on live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices)

Installing apps on live stores

Managing a live store comes with its own set of challenges, particularly concerning security, stability, and performance. Making changes, such as installing new apps, can feel risky if their potential impact isn't well understood. However, by following established best practices, you can minimize risks and maintain smooth operations, protecting your store's stability and conversion rates.

Combining manual testing in [development workspaces](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-development-workspace) with [A/B testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/ab-tests) is a highly effective strategy. These steps allow you to identify and address potential issues before implementing changes for all users.

## Instructions

### Step 1 - Performing manual tests in a Development Workspace

1. [Install](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-an-app) the app in a development workspace.
2. [Link](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app) your local files to the development workspace with VTEX IO.
3. Access the store via the development workspace URL: `{developmentWorkspaceName}--{accountName}.myvtex.com`.
4. Navigate the store and perform manual tests to ensure the app behaves as expected. Look for any functionality issues or unintended side effects.
5. Visit the master workspace (`{accountName}.myvtex.com`) to identify any unexpected changes introduced by the app.
6. If all tests pass, install the app in a [production workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-production-workspace);

### Step 2 - Running A/B tests

Set up an [A/B test](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-running-native-ab-testing) between the master workspace and the production workspace. During configuration, manually set traffic distribution for each workspace, directing a small percentage of users to the Production workspace.

> Avoid relying on automatic traffic segmentation, which splits traffic 50/50, as it exposes a larger audience to potential issues.

### Step 3 - Promoting your changes

1. If your changes involve a new major version of the Store Theme, refer to the [Migrating CMS settings after a major theme update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update) guide to avoid losing Admin page template settings.
2. Once validated, [promote the production workspace to master](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-promoting-a-workspace-to-master), making the new configurations public for all your users.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

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/Perks/best-practices/vtex-io-documentation-installing-apps-in-live-stores-best-practices.md)

[Migrating CMS settings after a Store Theme major update« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices//docs/guides/vtex-io-documentation-migrating-cms-settings-after-major-update)[Migrating your storefront from Legacy CMS Portal to Store FrameworkNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices//docs/guides/vtex-io-documentation-migrating-storefront-from-legacy-to-io)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices%23instructions)

[Step 1 - Performing manual tests in a Development Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices%23step-1-performing-manual-tests-in-a-development-workspace)[Step 2 - Running A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices%23step-2-running-ab-tests)[Step 3 - Promoting your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices%23step-3-promoting-your-changes)

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/Perks/best-practices/vtex-io-documentation-installing-apps-in-live-stores-best-practices.md)

Copy page

On this page

ON THIS PAGE

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices%23instructions)

[Step 1 - Performing manual tests in a Development Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices%23step-1-performing-manual-tests-in-a-development-workspace)[Step 2 - Running A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices%23step-2-running-ab-tests)[Step 3 - Promoting your changes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices/docs/guides/vtex-io-documentation-installing-apps-in-live-stores-best-practices%23step-3-promoting-your-changes)

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 faststore headless cms widgets 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/faststore/headless-cms-widgets/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/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/faststore/headless-cms-widgets/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/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/faststore/headless-cms-widgets/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/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/faststore/headless-cms-widgets/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore)

[FastStore versions and support levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/getting-started-faststore-versions-and-support-levels)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/getting-started-overview)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/webops-dashboard)

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-overview)

[Managing content with 'scopes' and 'requiredScopes'](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-managing-content-with-scopes-and-requiredscopes)

[Multiple page templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-multiple-page-template)

[Previewing Headless CMS in development mode](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-previewing-changes-in-development-mode)

[Widgets for Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets)

[Customizing pages with Dynamic Content](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/dynamic-content-overview)

[Developer tools and references](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/developer-tools-overview)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/styling-overview)

[UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/components-index)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/sdk-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/developing-and-overriding-components-overview)

[Extending the FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/api-extensions-overview)

[Managing URLs with redirects and rewrite paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/troubleshooting-overview)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore)

[FastStore versions and support levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/getting-started-faststore-versions-and-support-levels)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/getting-started-overview)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/webops-dashboard)

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-overview)

[Managing content with 'scopes' and 'requiredScopes'](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-managing-content-with-scopes-and-requiredscopes)

[Multiple page templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-multiple-page-template)

[Previewing Headless CMS in development mode](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-previewing-changes-in-development-mode)

[Widgets for Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets)

[Customizing pages with Dynamic Content](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/dynamic-content-overview)

[Developer tools and references](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/developer-tools-overview)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/styling-overview)

[UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/components-index)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/sdk-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/developing-and-overriding-components-overview)

[Extending the FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/api-extensions-overview)

[Managing URLs with redirects and rewrite paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/troubleshooting-overview)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/storefront-best-practices)

---

[Storefront development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/storefront-development)

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore)

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-overview)

Widgets for Headless CMS

Widgets are interface elements in the [Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-overview) that merchants can use to enhance store sections. These can include date pickers, dropdown menus, image uploaders, and more, helping editors create and edit content.

In this guide, you will find:

* [Widgets available](#widgets-available): An overview of each widget and its function.
* [Instructions on how to add a widget to a section](#adding-a-widget-to-a-store-section): A guide with instructions on incorporating a widget into a new store section.

## Widgets available

Below is a brief description of the widgets that can be implemented and used in the Headless CMS interface in the VTEX Admin. For detailed information about each widget, click the respective widget name.

| Widget name                             | Description                                                                                |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [checkboxes](#checkboxes)               | Displays checkboxes for selecting options in forms.                                                                                |
| [image-uploader](#image-uploader)       | Uploads images from your local machine.                                                                                |
| [date-time](#date-time)                 | Provides a calendar popup for selecting a date and time.                                                                                |
| [draftjs-rich-text](#draftjs-rich-text) | Rich text editor for formatting and styling store text.                                                                                |
| [media-gallery](#media-gallery)         | Uploads or selects existing images or videos from the [Media](https://read.calvincode.net/reader?url=https://vtexhelp.myvtex.com/tutorial/media-overview--31fhjHTt4TBoo50AmGQ9b2). |

### `checkboxes`

Displays a checkbox commonly used in forms to select an option. The following image shows how the `checkboxes` are displayed within the headless CMS interface:

![{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAABCAIAAAB2XpiaAAAACXBIWXMAAAPoAAAD6AG1e1JrAAAAFklEQVR4nGNQVVWbP3/+////58+fDwAmbwcodtX4RgAAAABJRU5ErkJggg==","img":{"src":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-three___77a45e8e239de651e1169b6b15ebe222.gif","width":543,"height":107,"type":"gif"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-three___77a45e8e239de651e1169b6b15ebe222.gif)

### `image-uploader`

Displays a card to upload an image from your local machine. The following image shows how the `image-uploader` is displayed within the headless CMS interface:

![{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAABCAIAAAB2XpiaAAAACXBIWXMAABYlAAAWJQFJUiTwAAAAFUlEQVR4nGNIz8g0M7cwM7eYMHEiABkzBDVqZuuBAAAAAElFTkSuQmCC","img":{"src":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-four___58dba186180d5e731436a06c41a8c454.png","width":750,"height":238,"type":"png"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-four___58dba186180d5e731436a06c41a8c454.png)

> The `image-uploader` is one of the available widgets. Still, we recommend using the [media gallery](#media-gallery) widget, which allows you to select and upload not only images but also videos from the [Media](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/media-overview--31fhjHTt4TBoo50AmGQ9b2) module.

### `date-time`

Provides a calendar popup for selecting a date and time. It is ideal for displaying deadlines, event times, or any scenario where you need to specify a specific date and time within your headless CMS content. For example, you can showcase a product's expiration date or display a time-limited coupon badge. The following image shows how the `date-time` is displayed within the headless CMS interface:

![{"base64":"  ","img":{"width":621,"height":420,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":123732,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-five___ddd15e6fbc00b8687276bd6bf6d72e78.gif"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-five___ddd15e6fbc00b8687276bd6bf6d72e78.gif)

### `draftjs-rich-text`

Displays an editor that allows formatting and styling the store text. The following image shows how the `draftjs-rich-text` is displayed within the headless CMS interface:

![{"base64":"  ","img":{"width":574,"height":223,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":5924,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-six___b1c1f6a8a646661428c75d7e68dcdbd2.png"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-six___b1c1f6a8a646661428c75d7e68dcdbd2.png)

### `media-gallery`

Displays a card to upload or select an existing image from the [Media](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/media-overview--31fhjHTt4TBoo50AmGQ9b2) module. The following image shows how the `media-gallery` is displayed within the headless CMS interface:

> The difference between the [image-uploader](#image-uploader) and the `media-gallery` is that when you click the `media-gallery` property, you can select or upload an image or a video from the [Media](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/media-overview--31fhjHTt4TBoo50AmGQ9b2) module. The `image-uploader` on the other hand, only allows you to upload images from your machine.

![{"base64":"  ","img":{"width":577,"height":254,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":9464,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-seven___ab9decd87c30ee0c44428ff83dcae592.png"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-seven___ab9decd87c30ee0c44428ff83dcae592.png)

## Adding a widget to a store section

Widgets are useful when you've [created a new store section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/building-sections-creating-a-new-section) and want to add a new property to it. To illustrate how a widget can be used in a store section, here's an example using the [media-gallery](#media-gallery) widget in the new `Custom Newsletter` section, based on the [Newsletter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/organisms-newsletter) native section.

> To create a new section, such as the `Custom Newsletter`, follow the instructions in the guide [Creating a new store section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/building-sections-creating-a-new-section).

1. Open your store project code in a code editor and navigate to the `cms/faststore` folder.
2. Open the `sections.json` file.
3. In the `sections.json` file, find the section where you want to add the widget. In the following `sections.json` file example, the new section, `Custom Newsletter`, receives the [media-gallery](#media-gallery) widget.
1. Open the terminal and run `yarn cms-sync` to sync the new section with the Headless CMS. Once the changes are synced, you will see the following message: `info: CMS synced successfully...`.
2. Go to the VTEX Admin and access **Storefront > Headless CMS**.
3. Open the page where you want to add the new section. In this example, we will add the `Custom Newsletter` to `Home`.
4. Add the section to the page, and you will notice the widget you added, the [media-gallery](#media-gallery).
![{"base64":"  ","img":{"width":1368,"height":854,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":1741010,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-one___6c8c5e28b43487efc6f6048afd8d8d15.gif"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-one___6c8c5e28b43487efc6f6048afd8d8d15.gif)
5. Click `Preview` to view the new component with the new image.
![{"base64":"  ","img":{"width":1142,"height":558,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":108362,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-two___9c76a69ce03639b33faa85eb2a7cb367.png"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-two___9c76a69ce03639b33faa85eb2a7cb367.png)

checkboxes

`1

"activate": {

2

 "title": "Activate Cupom",

3

 "type": "boolean",

4

 "default": true,

5

 "widget": {

6

 "ui:widget": "checkboxes"

7

 }

8

},

`

Contributors

2

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

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/faststore/docs/headless-cms/widgets.mdx)

[Previewing Headless CMS in development mode« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-previewing-changes-in-development-mode)[Customizing pages with Dynamic ContentNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/dynamic-content-overview)

Contributors

2

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

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Widgets available](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23widgets-available)

[checkboxes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23checkboxes)[image-uploader](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23image-uploader)[date-time](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23date-time)[draftjs-rich-text](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23draftjs-rich-text)[media-gallery](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23media-gallery)

[Adding a widget to a store section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23adding-a-widget-to-a-store-section)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/faststore/docs/headless-cms/widgets.mdx)

Copy page

On this page

ON THIS PAGE

[Widgets available](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23widgets-available)

[checkboxes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23checkboxes)[image-uploader](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23image-uploader)[date-time](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23date-time)[draftjs-rich-text](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23draftjs-rich-text)[media-gallery](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23media-gallery)

[Adding a widget to a store section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/headless-cms-widgets/docs/guides/faststore/headless-cms-widgets%23adding-a-widget-to-a-store-section)

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=)