[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 store components 3.178.5 SearchBar 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.store-components@3.178.5/SearchBar/docs/guides)

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

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

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

VTEX IO Apps

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

---

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

---

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

---

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

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/guides/functional-apps)

---

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

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/guides/pixel-apps)

---

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

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/updates/release-notes)

VTEX IO Apps

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

---

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

---

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

---

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

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/guides/functional-apps)

---

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

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/guides/pixel-apps)

---

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

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/guides/vtex-io-deprecated-apps)

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/vtex-io-apps)

Search Bar

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

Version: 3.178.5

Latest version: 3.178.5

The `search-bar` component shows a search bar with autocomplete options and displays the matching products as well. This component can be imported and used by any VTEX App.

![{"base64":"  ","img":{"width":1892,"height":694,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":884048,"url":"https://user-images.githubusercontent.com/67270558/147773132-c3e9d1ee-7878-465d-95b3-69903ded5937.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/67270558/147773132-c3e9d1ee-7878-465d-95b3-69903ded5937.png)

## Configuration

1. Import the `vtex.store-components` app to your theme's dependencies in the `manifest.json` file as in the following example:

`1

 "dependencies": {

2

 "vtex.store-components": "3.x"

3

 }

`

1. Add the `search-bar` block into the [header](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-header) component. For example:

`1

 "header.full": {

2

 "blocks": [

3

 "login",

4

 "minicart",

5

 "logo",

6

+ "search-bar",

7

 "menu-link",

8

 "telemarketing",

9

 "category-menu"

10

 ]

11

 },

`

1. Then, declare the `search-bar` block using the props stated in the [Props](#props) table. For example:

### Props

| Prop name                     | Type                                        | Description                                                                                | Default value |
| ----------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| attemptPageTypeSearch         | Boolean                                     | If true when clicked on result link of brand, department or category will link to the corresponding brand, department or category page. When false will always go to a full text search page.                                                                                | false         |
| autocompleteAlignment         | [HorizontalAlignment](#horizontalalignment) | Autocomplete Horizontal alignment. Possible values are: left, center, right.                                                                                | left          |
| autocompleteFullWidth         | Boolean                                     | If true, the autocomplete will fill the whole window horizontally.                                                                                | false         |
| autoFocus                     | Boolean                                     | Define if the search input should autofocus or not                                                                                | \-            |
| blurOnSubmit                  | Boolean                                     | Define if input should blur on submit.                                                                                | false         |
| classes                       | CustomCSSClasses                            | Overrides default CSS handles. To better understand how this prop works, check [this document](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/css-handles%23usecustomclasses). Note that this is only helpful if you're using this block as a React component.                                                            | undefined     |
| containerMode                 | enum                                        | Defines how the autocomplete component should be displayed. Possible values are: overlay (suggestions overlapping other components) and container (displays the suggestion within a container).                                                                                | overlay       |
| compactMode                   | Boolean                                     | Define when to use the compact version of the component                                                                                | \-            |
| customSearchPageUrl           | string                                      | Template for a custom url. It can have a substring ${term} used as placeholder to interpolate the searched term. (e.g. /search?query=${term})                                                                                | \-            |
| disableBlurAndTouchEndHandler | Boolean                                     | The autocomplete can have touchable/clickable components. Interacting with those components may trigger blur and touch events that will close the autocomplete. When set to true, this prop will disable those handlers.                                                                              | false         |
| displayMode                   | [DisplayMode](#displaymode)                 | Define the component display mode, such as which buttons should be visible.                                                                                | clear-button  |
| emptyPlaceholder              | String!                                     | Shows a placeholder when the ResultList hasn't results to displayed                                                                                | \-            |
| hasIconLeft                   | Boolean                                     | Define if the search icon is on left or right position                                                                                | \-            |
| iconClasses                   | String                                      | ![{"base64":"  ","img":{"width":71,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://img.shields.io/badge/-deprecated-red"}}](https://read.calvincode.net/reader?url=https://img.shields.io/badge/-deprecated-red) Custom classes for the search icon. Use the CSS handle searchBarIcon.            | \-            |
| inputType                     | enum                                        | Defines the value for the type HTML attribute (from the <input> field). Possible values are: search and text. We strongly recommend you to use search as it fixes some iOS issues. The text value is only kept as default for backwards compatibility.                                                | text          |
| maxWidth                      | Number \| String                            | Max width of the search bar                                                                                | \-            |
| minSearchTermLength           | Number                                      | If defined, it will block searches where the term length is lesser than minSearchTermLength.                                                                                | \-            |
| openAutocompleteOnFocus       | Boolean                                     | Defines if autocomplete should be open on input focus or not.                                                                                | false         |
| placeholder                   | String!                                     | Placeholder to be used on the input                                                                                | \-            |
| submitOnIconClick             | Boolean                                     | ![{"base64":"  ","img":{"width":71,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://img.shields.io/badge/-deprecated-red"}}](https://read.calvincode.net/reader?url=https://img.shields.io/badge/-deprecated-red) Defines if search icon should submit on click. Use the displayMode prop instead. | false         |

#### `DisplayMode`

| Enum name                | Enum value                 | Empty state                                                                                | Filled state                                                                                |
| ------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clear-button             | 'clear-button'             | ![{"base64":"  ","img":{"width":240,"height":38,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":2136,"url":"https://user-images.githubusercontent.com/12702016/74764904-5cc5e580-5261-11ea-9df8-484cf457c266.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12702016/74764904-5cc5e580-5261-11ea-9df8-484cf457c266.png) | ![{"base64":"  ","img":{"width":246,"height":38,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":2405,"url":"https://user-images.githubusercontent.com/12702016/74764917-60f20300-5261-11ea-8911-11c8fd9582d9.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12702016/74764917-60f20300-5261-11ea-8911-11c8fd9582d9.png) |
| search-and-clear-buttons | 'search-and-clear-buttons' | ![{"base64":"  ","img":{"width":265,"height":38,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":2294,"url":"https://user-images.githubusercontent.com/12702016/74764924-62bbc680-5261-11ea-9f1d-2118274da996.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12702016/74764924-62bbc680-5261-11ea-9f1d-2118274da996.png) | ![{"base64":"  ","img":{"width":265,"height":38,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":2865,"url":"https://user-images.githubusercontent.com/12702016/74764928-64858a00-5261-11ea-9ed2-42da887e6641.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12702016/74764928-64858a00-5261-11ea-9ed2-42da887e6641.png) |
| search-button            | 'search-button'            | ![{"base64":"  ","img":{"width":240,"height":38,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":2136,"url":"https://user-images.githubusercontent.com/12702016/74764929-65b6b700-5261-11ea-815c-ecc9f0c44e0f.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12702016/74764929-65b6b700-5261-11ea-815c-ecc9f0c44e0f.png) | ![{"base64":"  ","img":{"width":240,"height":38,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":2528,"url":"https://user-images.githubusercontent.com/12702016/74764934-66e7e400-5261-11ea-8a86-59da9a1c0faa.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12702016/74764934-66e7e400-5261-11ea-8a86-59da9a1c0faa.png) |

## Using SearchBar with Intelligent Search

To improve the search experience usign the SearchBar component, such as the autocomplete option, you must use the component within [Search app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search) responsible for handling the [Intelligent Search (IS)](https://read.calvincode.net/reader?url=https://help.vtex.com/tracks/vtex-intelligent-search?%5Fga=2.220970832.979717665.1650285782-1001456323.1619912759) solution in IO stores.

The IS communicates with the `autocomplete-result-list.v2` block exported by the Search app, and the block displays previous search results based on current and previous searches.

Follow the [Search documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.search) to add the Search app to your store.

## Customization

To apply CSS customizations in this and other blocks, follow the [Using CSS handles for store customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization) guide.

| CSS Handles                     |
| ------------------------------- |
| compactMode                     |
| externalSearchButtonWrapper     |
| paddingInput                    |
| searchBarContainer              |
| searchBarInnerContainer--opened |
| searchBarInnerContainer--filled |
| searchBarIcon                   |
| searchBarIcon--clear            |
| searchBarIcon--external-search  |
| searchBarIcon--prefix           |
| searchBarIcon--search           |
| suffixWrapper                   |

See also

[Vtex.store ComponentsVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/apps/vtex.store-components)[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/apps/vtex.store-components@3.178.5/SearchBar%23configuration)

[Props](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/apps/vtex.store-components@3.178.5/SearchBar%23props)

[Using SearchBar with Intelligent Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/apps/vtex.store-components@3.178.5/SearchBar%23using-searchbar-with-intelligent-search)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components@3.178.5/SearchBar/docs/apps/vtex.store-components@3.178.5/SearchBar%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 faststore analytics sending custom events 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/analytics-sending-custom-events/docs/guides)

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

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

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

Storefront Development

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore)

[FastStore versions and support levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/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/analytics-sending-custom-events/docs/guides/faststore/getting-started-overview)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/webops-dashboard)

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

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

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/styling-overview)

[UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/components-index)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/sdk-overview)

[Analytics](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-overview)

[sendAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-send-analytics-event)

[useAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-use-analytics-event)

[Sending custom events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events)

[Extending and customizing native types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-extending-and-customizing-native-types)

[Use case: Implementing custom newsletter analytics events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-implementing-custom-newsletter-analytics-events)

[Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/cart-overview)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/search-overview)

[Session](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/session-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/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/analytics-sending-custom-events/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/analytics-sending-custom-events/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/analytics-sending-custom-events/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/troubleshooting-overview)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/updates/release-notes)

Storefront Development

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

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore)

[FastStore versions and support levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/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/analytics-sending-custom-events/docs/guides/faststore/getting-started-overview)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/webops-dashboard)

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

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

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/styling-overview)

[UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/components-index)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/sdk-overview)

[Analytics](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-overview)

[sendAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-send-analytics-event)

[useAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-use-analytics-event)

[Sending custom events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events)

[Extending and customizing native types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-extending-and-customizing-native-types)

[Use case: Implementing custom newsletter analytics events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-implementing-custom-newsletter-analytics-events)

[Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/cart-overview)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/search-overview)

[Session](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/session-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/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/analytics-sending-custom-events/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/analytics-sending-custom-events/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/analytics-sending-custom-events/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/troubleshooting-overview)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/storefront-best-practices)

---

[Storefront development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/storefront-development)

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/sdk-overview)

[Analytics](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-overview)

Sending custom events

Even though the [Analytics](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-overview) module natively supports [Google Analytics ecommerce events](https://read.calvincode.net/reader?url=https://support.google.com/analytics/answer/14434488?hl=en), you may need to track customer activity not covered by default events. In such cases, you can trigger and intercept custom events using the [sendAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) and [useAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) functions. In this guide, you'll learn how to define and send custom events.

> For a practical example of sending custom events, see the [Implementing custom newsletter analytics events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-implementing-custom-newsletter-analytics-events) guide.

## Instructions

### Step 1 - Declaring an interface for your custom event

To trigger a custom event, you must define an interface that describes the structure of your event object, including its properties and types. You can do this in three ways:

* [Creating a new event interface](#creating-a-new-event-interface)
* [Extending existing types from the Analytics module](#extending-existing-types-from-the-analytics-module)
* [Overriding multiple types](#overriding-multiple-types)

#### Creating a new event interface

To create a custom event interface, use the [sendAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) function.

In the following example, we define a custom event called `WishlistEvent` to track when a user adds a product to their wishlist. Since this is not a standard ecommerce event, we set `isEcommerceEvent: false`:

`1

import { sendAnalyticsEvent } from '@faststore/sdk'

2

3

interface WishlistEvent {

4

 name: 'wishlist_event'

5

 isEcommerceEvent: false

6

 params: {

7

 productId: string

8

 productName: string

9

 userId: string

10

 isLoggedIn: boolean

11

 }

12

}

13

14

sendAnalyticsEvent<WishlistEvent>({

15

 name: 'wishlist_event',

16

 isEcommerceEvent: false,

17

 params: {

18

 productId: '12345',

19

 productName: 'Example Product',

20

 userId: 'user-abc',

21

 isLoggedIn: true

22

 }

23

})

`

This custom event interface captures when a user adds a product to their wishlist, logging details like `productId`, `productName`, and whether the user is logged in (`isLoggedIn`). By setting `isEcommerceEvent: false`, the parameters are sent at the top level of the event payload, following the [Google Analytics 4 format for custom events](https://read.calvincode.net/reader?url=https://support.google.com/analytics/answer/14240153?hl=en).

#### Extending existing types from the Analytics module

If your event is related to an existing one, you can extend relevant types from the Analytics module. You can do this by using the [TypeScript generics](https://read.calvincode.net/reader?url=https://www.typescriptlang.org/docs/handbook/2/generics.html) with the [sendAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) function.

The following example extends the `AddToCartEvent` interface to include the `couponCode` property, which is useful for tracking if a customer applied a coupon code when adding an item to the cart:

`1

import type { AddToCartEvent } from '@faststore/sdk'

2

import { sendAnalyticsEvent } from '@faststore/sdk'

3

4

interface AddToCartExtended extends AddToCartEvent {

5

 couponCode: string

6

}

7

8

/* ... */

9

10

sendAnalyticsEvent<AddToCartExtended>({ name, params, couponCode })

`

#### Overriding multiple types

If you have multiple custom events, such as adding/removing items from the cart or viewing products, you can define a unified type to handle them all. This approach simplifies firing multiple events from the same interface.

`1

/* types.ts */

2

import { sendAnalyticsEvent } from '@faststore/sdk'

3

4

type AddToCartExtended = /* ... */

5

type RemoveFromCartExtended = /* ... */

6

type ViewItemExtended = /* ... */

7

type SelectItemExtended = /* ... */

8

9

type ExtendedEvents =

10

| AddToCartExtended

11

| RemoveFromCartExtended

12

| ViewItemExtended

13

| SelectItemExtended

14

15

type SendExtendedAnalyticsEvent = (event: ExtendedEvents) => void

16

17

export const sendExtendedAnalyticsEvent: SendExtendedAnalyticsEvent = (event) =>

18

sendAnalyticsEvent<ExtendedEvents>(event)

`

`1

/* MyComponent.tsx */

2

import { sendExtendedAnalyticsEvent } from './types'

3

4

/* ... */

5

6

sendExtendedAnalyticsEvent({ /* Extended event object */})

`

The example above sets up a flexible way to fire multiple custom events. Instead of managing multiple event types separately, the purpose of the example is to handle them all through a single interface. You can use this setup to track diverse customer interactions, such as adding/removing products from the cart, viewing products, or saving items to the wishlist.

### Step 2 - Intercepting custom events

After defining the event interface, you'll need to intercept these events using the `useAnalyticsEvent` hook. Below is an example of how to set up an event handler:

`1

import { useAnalyticsEvent } from '@faststore/sdk'

2

3

import type { ArbitraryEvent } from './types'

4

5

export const AnalyticsHandler = () => {

6

useAnalyticsEvent((event: ArbitraryEvent) => {

7

})

8

9

/* ... */

10

11

return null

12

}

`

Note that to target extended properties of events, you'll also need to configure the types of your [useAnalyticsEvent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) callback function to expect an event of that type.

`1

import { useAnalyticsEvent } from '@faststore/sdk'

2

3

import type { ExtendedEvents } from './types'

4

5

export const AnalyticsHandler = () => {

6

7

useAnalyticsEvent((event: ExtendedEvents) => {

8

 /* ... */

9

})

10

11

/* ... */

12

13

return null

14

}

`

> By typing the callback function with the extended types, you can reference properties not natively provided by the Analytics module.

### Step 3 - Firing custom events

Now that you've declared your event interface and intercepted it with the `useAnalyticsEvent` hook, you can implement it in your components to fire the event.

`1

import { useCallback } from 'react'

2

import { sendAnalyticsEvent } from '@faststore/sdk'

3

4

const MyComponent = () => {

5

const handleCustomEvent = useCallback(() => {

6

 sendAnalyticsEvent({

7

 name: 'custom_action',

8

 isEcommerceEvent: false,

9

 params: {

10

 action_type: 'button_click',

11

 component_name: 'MyComponent',

12

 timestamp: new Date().toISOString()

13

 }

14

 })

15

}, [])

16

17

return <button onClick={handleCustomEvent}>Trigger Custom Event</button>

18

}

`

> Use `isEcommerceEvent: false` for custom events that track user interactions, feature usage, or other non-commerce activities. Reserve the default `isEcommerceEvent: true` (or omit it) for events related to the shopping funnel (add to cart, purchase, etc.).

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/_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/analytics-sending-custom-events/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

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/sdk/analytics/sending-custom-events.mdx)

[useAnalyticsEvent« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-use-analytics-event)[Extending and customizing native typesNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-extending-and-customizing-native-types)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/_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/analytics-sending-custom-events/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

ON THIS PAGE

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events%23instructions)

[Step 1 - Declaring an interface for your custom event](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events%23step-1-declaring-an-interface-for-your-custom-event)[Step 2 - Intercepting custom events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events%23step-2-intercepting-custom-events)[Step 3 - Firing custom events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events%23step-3-firing-custom-events)

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/sdk/analytics/sending-custom-events.mdx)

Copy page

On this page

ON THIS PAGE

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events%23instructions)

[Step 1 - Declaring an interface for your custom event](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events%23step-1-declaring-an-interface-for-your-custom-event)[Step 2 - Intercepting custom events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events%23step-2-intercepting-custom-events)[Step 3 - Firing custom events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/analytics-sending-custom-events/docs/guides/faststore/analytics-sending-custom-events%23step-3-firing-custom-events)

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 vtex io cross border stores 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-cross-border-stores/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/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-cross-border-stores/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-cross-border-stores/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-cross-border-stores/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-cross-border-stores/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-cross-border-stores/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/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-cross-border-stores/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/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-cross-border-stores/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-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores)

[Checking your store's binding ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/checking-your-stores-binding-id)

[Creating robots files for cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-creating-robots-files-for-cross-border-stores)

[Cross-border store content internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/cross-border-custom-urls-1)

[Managing landing pages in cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-managing-landing-pages-in-cross-border-stores)

[Indicating alternate versions of localized pages in cross border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-indicating-alternate-pages-in-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/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-cross-border-stores/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-updating-live-stores)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides)

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

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

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

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

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/troubleshooting)

---

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

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/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-cross-border-stores/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/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-cross-border-stores/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-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores)

[Checking your store's binding ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/checking-your-stores-binding-id)

[Creating robots files for cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-creating-robots-files-for-cross-border-stores)

[Cross-border store content internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/cross-border-custom-urls-1)

[Managing landing pages in cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-managing-landing-pages-in-cross-border-stores)

[Indicating alternate versions of localized pages in cross border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-indicating-alternate-pages-in-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/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-cross-border-stores/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-updating-live-stores)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/storefront-best-practices)

---

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

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework)

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

Setting up cross-border stores

Cross-border stores are a specialized type of [multistore](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/creating-multi-store-multi-domain--tutorials%5F510?locale=en), where a single VTEX account manages multiple stores across different countries or regions.

This setup is ideal for stores with different brands and business models that require multiple operational environments. In a multistore setup — also known as a subaccount or multidomain — each store can be configured independently, which means that layouts, products, prices, and logistics can be tailored to each region and domain.

In a cross-border context, a multistore setup allows a single VTEX account to manage multiple stores, such as:

* `http://{storeName}.com/en` (English store)
* `http://{storeName}.com/pt` (Portuguese store)

> To become a cross-border store, open a [VTEX support ticket](https://read.calvincode.net/reader?url=https://help-tickets.vtex.com/smartlink/sso/login/zendesk) and request the setup of a multistore environment.

## Before you begin

### Define your operation

Before implementing your cross-border store, make sure you have the following information ready:

* **Target regions:** Identify the countries/regions where your store will operate.
* **Currencies and Languages:** Determine accepted payment currencies and supported site languages.
* **Inventory management:** Decide if inventory will be managed from Brazil or locally in each country/region.
* **Tax and Export partner:** If using fulfillment from Brazil, choose a partner for handling export taxes and fees. To find your partner, check out the [Partners](https://read.calvincode.net/reader?url=https://vtex.com/en-us/partners/) page on the VTEX website.
* **Catalog translation:** Check if your catalog is translated or needs localization for each country/region.
* **Promotions:** Plan the types of promotions for each store. Learn about the types available in [Promotions](https://read.calvincode.net/reader?url=https://help.vtex.com/subcategory/benefits--1yTYB5p4b6iwMsUg8uieyq) guides.
* **Operations:** Consider any existing physical stores, sellers, or other operations abroad. Learn more in [VTEX account types](https://read.calvincode.net/reader?url=https://help.vtex.com/tracks/vtex-store-overview--eSDNk26pdvemF3XKM0nK9/4yPqZQyj0t675QpcG7H6yl%23vtex-account-types)
* **Teams:** Identify if different teams will manage each country/region’s ecommerce operations.
* **ERP Systems:** Confirm if each country/region has its own ERP or a centralized system.
* **Payment gateway:** Ensure you have a gateway that supports multiple currencies.
* **Domains:** Define the primary and secondary domains for your stores. Learn more in [Rules for main hosts](https://read.calvincode.net/reader?url=https://help.vtex.com/pt/tutorial/configuring-the-store-domain--tutorials%5F2450%23rules-for-main-host).

This information will help you to choose the most suitable architecture for your cross-border store.

### Choose your store architecture

After defining your operation based on the topics above, choose the architecture for your cross-border store following the section [Multi-language and multi-currency](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/store-architecture%23multi-language-and-multi-currency) within the Store Architecture guide.

## Essential concepts

To better understand how a VTEX cross-border multistore works, it's essential to understand the key concepts of bindings and trade policies.

### Binding

In VTEX, **binding** is the process of linking a website, store name, and trade policy to create a unique identifier for each store. This is essential for managing multiple stores within a single VTEX account.

Each store has a unique binding value, which is crucial for routing and configuring store-specific settings.

> To check the `binding` value of your stores, follow the [Checking your store's binding id](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/checking-your-stores-binding-id) guide.

### Trade Policies

A **trade policy** is a set of configurations that define a store's catalog, pricing, and logistics strategy. Each store can have its own trade policy, allowing for different setups depending on the market. For example, if the pricing structure differs between your stores in Spain and France, you'll need separate trade policies.

However, if two stores share the same logistics, catalog, and prices, they can use a common trade policy.

> To learn more, see the guide [How trade policies work](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV).

## Guides in this section

[Checking your store's binding idUnderstand how to identify the unique binding ID for each store in your cross-border setup.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/checking-your-stores-binding-id)[Creating robots files for cross-border storesLearn how to configure \`robots.txt\` files to manage search engine indexing for cross-border stores.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-robots-files-for-cross-border-stores)[Cross-border store content internationalizationDiscover how to customize URLs and manage content localization for cross-border stores.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/cross-border-custom-urls-1)[Managing landing pages in cross-border storesLearn how to manage landing pages tailored for different regions.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-managing-landing-pages-in-cross-border-stores)[Indicating alternate versions of localized pages in cross border storesDiscover how to set up alternate page versions in cross-border stores.See more](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-indicating-alternate-pages-in-cross-border-stores)

Contributors

1

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

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/Storefront-Guides/store-framework-setting-up-cross-border-stores.md)

[Setting up Google Tag Manager events and triggers« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores//docs/guides/vtex-io-documentation-setting-up-google-tag-manager)[Checking your store's binding IDNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores//docs/guides/checking-your-stores-binding-id)

Contributors

1

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

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23before-you-begin)

[Define your operation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23define-your-operation)[Choose your store architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23choose-your-store-architecture)

[Essential concepts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23essential-concepts)

[Binding](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23binding)[Trade Policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23trade-policies)

[Guides in this section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23guides-in-this-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/guides/vtex-io/Storefront-Guides/store-framework-setting-up-cross-border-stores.md)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23before-you-begin)

[Define your operation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23define-your-operation)[Choose your store architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23choose-your-store-architecture)

[Essential concepts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23essential-concepts)

[Binding](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23binding)[Trade Policies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23trade-policies)

[Guides in this section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-cross-border-stores/docs/guides/store-framework-setting-up-cross-border-stores%23guides-in-this-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=)


[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 using events to trigger side effects on store components 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-using-events-to-trigger-side-effects-on-store-components/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-dealing-with-events)

[Collecting user session data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-collecting-user-session-data)

[Cleaning cart data on log out](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-cleaning-cart-data-on-log-out)

[Improving filter navigator experience](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-improving-filter-navigator-experience)

[Using events to trigger side effects on store components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-updating-live-stores)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-styling)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-dealing-with-events)

[Collecting user session data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-collecting-user-session-data)

[Cleaning cart data on log out](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-cleaning-cart-data-on-log-out)

[Improving filter navigator experience](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-improving-filter-navigator-experience)

[Using events to trigger side effects on store components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/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-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-updating-live-stores)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/storefront-best-practices)

---

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/storefront-development)

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/store-framework-dealing-with-events)

[Using events to trigger side effects on store components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components)

Using events to trigger side effects on store components

Events or pixel events are notifications broadcast by your storefront whenever a user performs a tracked action, such as:

* Adding an item to the cart (`addToCart` event).
* Removing an item from the cart (`removeItem` event).
* Accessing a loaded page (`pageView` event).
* Viewing a product (`productImpression` event).

Analytics tools commonly use these events to track users' shopping behavior and interactions across your store pages.

You can also use events to create dynamic interactions between your store components by using the `customPixelEventId` prop. These events can generate side effects in the UI, triggering automatic behaviors in your store components as needed.

The `customPixelEventId` prop can be used as either an event sender or receiver, depending on its implementation. When used in a sender component, it emits an event in response to user interaction. In a receiver component, it listens for that specific event and triggers a corresponding UI update.

The prop's value must be a unique ID, enabling blocks to identify which event is being sent or received during user interaction in the UI.

The following table lists the components that support the `customPixelEventId` prop:

| Block name         | Behavior                                    |
| ------------------ | ------------------------------------------- |
| add-to-cart-button | Sends an event when clicked.                |
| minicart.v2        | Receives an event and performs a UI action. |
| drawer-trigger     | Sends an event when clicked.                |
| drawer             | Receives an event and performs a UI action. |
| modal-trigger      | Sends an event when clicked.                |
| modal-layout       | Receives an event and performs a UI action. |

## Use case example

In this section, we describe how events and the `customPixelEventId` prop can trigger side effects in the interface. Follow the steps below to configure the [Minicart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.minicart) to automatically open when a new product is added using the [Add to Cart Button](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.add-to-cart-button).

![{"base64":"  ","img":{"width":640,"height":504,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":4410411,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components-0.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components-0.gif)

### Instructions

#### Step 1 - Add dependencies

In your theme's `manifest.json` file, make sure the `minicart` and `add-to-cart-button` apps are listed as dependencies:

`1

"dependencies": {

2

 "vtex.minicart": "2.x",

3

 "vtex.add-to-cart-button": "0.x"

4

}

`

#### Step 2 - Configure the event sender

In your store theme code, declare the `customPixelEventId` prop in the block responsible for sending the desired event, passing a unique ID as its value. Example:

`1

{

2

 "add-to-cart-button#example": {

3

 "props": {

4

 "customPixelEventId": "example-add-to-cart"

5

 }

6

 },

7

}

`

#### Step 3 - Configure the event receiver

In the `minicart.v2` block, declare the `customPixelEventName` prop in the block responsible for listening for the desired event. Use the same unique ID that you declared in the sender block. Example:

`1

{

2

 "minicart.v2": {

3

 "props": {

4

 "customPixelEventName": "example-add-to-cart"

5

 },

6

 "children": ["minicart-base-content"]

7

 }

8

}

`

> The `customPixelEventName` prop triggers the `minicart.v2` to open automatically in the interface whenever it detects a pixel event with the specified name. If you also set a `customPixelEventId` prop on the sender, the `minicart.v2` opens only if both the event's name and custom ID match. Learn more in [Minicart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.minicart).

After saving your changes and [deploying your new Store Theme version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available), the Add to Cart Button component will send the `example-add-to-cart` event when clicked. The Minicart will then automatically open in response to any event with this ID.

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/_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/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/_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/Storefront-Guides/concepts-1/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components.md)

[Improving filter navigator experience« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components//docs/guides/vtex-io-documentation-improving-filter-navigator-experience)[Configuring Analytics (Google Tag Manager)Next »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components//docs/guides/store-framework-configuring-analytics-google-tag-manager)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/_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/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Use case example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components%23use-case-example)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components%23instructions)

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/Storefront-Guides/concepts-1/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components.md)

Copy page

On this page

ON THIS PAGE

[Use case example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components%23use-case-example)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components/docs/guides/vtex-io-documentation-using-events-to-trigger-side-effects-on-store-components%23instructions)

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