[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 oauth provider admin 2.x 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.oauth-provider-admin@2.x/docs/guides)

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

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

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

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/guides/vtex-io-deprecated-apps)

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/vtex-io-apps)

VTEX OAuth Provider

Official extension

Version: 2.3.1

Latest version: 2.3.1

> The specified version of the app (**2.x.0**) does not exist. This page is about the latest stable version, which is **2.3.1**.

Use VTEX authentication as an IdP for your applications using the well-known OAuth2 protocol (<https://tools.ietf.org/html/rfc6749>). You can choose between **admin** or **store** credentials, allowing other systems to use the VTEX login validation. This will not provide access to VTEX resources, only verify the user authentication.

The allowed flows so far are:

* Authentication Code (<https://tools.ietf.org/html/rfc6749#section-1.3.1>)

**\[IMPORTANT\] As Authentication Code is the only flow implemented, for security reasons the client must have a server side application that will exchange the code for a token (Access Token Request), using the private client secret as authentication method.**

The account must have the app `vtex.oauth-provider-admin` installed. It'll add "OAuth Provider" in "Account Settings".

An account can have many OAuth clients registered, with different settings:

* **Name**: readable identifier \[IT IS NOT THE CLIENT ID\]
* **Allowed URI's** : a list of URI\`s that can be used as return uri in the flow
* **Credential Type**: the type of VTEX authentication that will be used to login: _admin_ or _store_
   * **Admin**: uses default VTEX login page
   * **Store**: allows the account to set a custom login page url, which must have a VTEX ID login flow

After the registration, the client will be issued a **Client Id** and a **Client Secret**.

## How to use

The application that want to use VTEX as an IdP using OAuth2 can implement the Authentication Code flow (<https://tools.ietf.org/html/rfc6749#section-4.1>), using the following endpoints:

### Authorization request

`[GET] https://{{account}}.myvtex.com/_v/oauth2/auth?client_id={{client_id}}&scope=&response_type=code&redirect_uri={{redirect_uri}}` (<https://tools.ietf.org/html/rfc6749#section-4.1.1>)

* client\_id: the Client Id issued after the client registration \[REQUIRED\]
* redirect\_uri: the encoded URL that the authorization server will redirect the user-agent, with _code_ and _state_ as query string \[OPTIONAL\]
* scope: TBD \[IGNORED\]
* response\_type: type of the authentication flow. Must be **code** \[REQUIRED\]
* state: An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client \[RECOMMENDED\]

### Authorization response

If the resource owner grants the access request, the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI (<https://tools.ietf.org/html/rfc6749#section-4.1.2>)

* code: the authorization code generated by the authorization server
* state: the same "state" parameter received in the client authorization request

### Access Token request

`[POST] https://{{account}}.myvtex.com/\_v/oauth2/token` (<https://tools.ietf.org/html/rfc6749#section-4.1.3>). Send the following parameters using the "application/x-www-form-urlencoded" format in the HTTP request entity-body:

* grant\_type: value MUST be set to "authorization\_code" \[REQUIRED\]
* code: the authorization code received from the authorization server \[REQUIRED\]
* redirect\_uri: \[REQUIRED\], if the "redirect\_uri" parameter was included in the authorization request and their values MUST be identical.
* client\_id: issued client\_id \[REQUIRED\]
* client\_secret: issued client\_secret \[REQUIRED\]

### Access Token response

The authorization server issues an access token as below:

`1

{

2

 "access_token": {access_token},

3

 "token_type": "bearer"

4

}

`

## OAuth2 extension

The Introspect endpoint is a commmon extension to the OAuth2 framework that provides some information about the issued token, like _username_ and _user\_id_.

### Introspect request

`[GET] https://{{account}}.myvtex.com/oauth2/introspect?token={{access_token}}`

* access\_token: the token received from /token endpoint.

### Introspect response

A json with the following token properties:

* active: if the token still active
* scope: the scopes allowed to this token
* client\_id: the client\_id of the token
* username: the username used in the authentication
* user\_id: the user\_id from the user in the authentication
* exp: expiration date of the token

See also

[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[How to use](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.oauth-provider-admin@2.x%23how-to-use)

[Authorization request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.oauth-provider-admin@2.x%23authorization-request)[Authorization response](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.oauth-provider-admin@2.x%23authorization-response)[Access Token request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.oauth-provider-admin@2.x%23access-token-request)[Access Token response](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.oauth-provider-admin@2.x%23access-token-response)

[OAuth2 extension](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.oauth-provider-admin@2.x%23oauth2-extension)

[Introspect request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.oauth-provider-admin@2.x%23introspect-request)[Introspect response](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.oauth-provider-admin@2.x/docs/apps/vtex.oauth-provider-admin@2.x%23introspect-response)

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 searching by geocoordinates in master data v2 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/searching-by-geocoordinates-in-master-data-v2/docs/guides)

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

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

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

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data)

[Understanding Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/understanding-master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-best-practices)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-v2)

Schemas

Triggers

[Master Data v2 document saving flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-v2-document-saving-flow)

[Creating relationships between data entities using Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/creating-relationships-between-data-entities-using-master-data-v2)

[Using dynamic expressions on Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/using-dynamic-expressions-on-master-data-v2)

[Searching by geocoordinates in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2)

[Setting up alternate keys in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/setting-up-alternate-keys-in-master-data-v2)

[Setting up an auto increment field in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/setting-up-an-auto-increment-field-in-master-data-v2)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-v1)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data)

[Understanding Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/understanding-master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-best-practices)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-v2)

Schemas

Triggers

[Master Data v2 document saving flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-v2-document-saving-flow)

[Creating relationships between data entities using Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/creating-relationships-between-data-entities-using-master-data-v2)

[Using dynamic expressions on Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/using-dynamic-expressions-on-master-data-v2)

[Searching by geocoordinates in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2)

[Setting up alternate keys in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/setting-up-alternate-keys-in-master-data-v2)

[Setting up an auto increment field in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/setting-up-an-auto-increment-field-in-master-data-v2)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-v1)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides)

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/master-data-v2)

[Searching by geocoordinates in Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2)

Searching by geocoordinates in Master Data v2

To enable search by geocoordinates in Master Data v2, your JSON schema must contain an object with the properties `latitude` and `longitude`:

`1

{

2

"properties": {

3

 "{{yourFieldName}}": {

4

 "type": "object",

5

 "properties": {

6

 "latitude": { "type": "number" },

7

 "longitude": { "type": "number" }

8

 },

9

 "additionalProperties": false

10

 }

11

 }

12

}

`

Also, it must be configured as indexed:

`1

{

2

 "v-indexed": [ "{{yourFieldName}}" ]

3

}

`

## Saving documents

To save a document that can later be searched by geocoordinates, it must contain the object value configured as geocoordinates:

`1

{

2

 "{{yourFieldName}}": {

3

 "latitude": {{value}},

4

 "longitude": {{value}}

5

 }

6

}

`

## Filtering

To filter documents that contain a location nearby a given geocoordinate (measured in km), add a filter as a query parameter in this format:

`1

{{yourFieldName}}={{latitudeValue}},{{longitudeValue}},{{integer}}km

`

See an example:

`1

address.location=-23.01227,-43.46163,25km

`

## Ordering search results by distance

To order documents by distance from a given geocoordinate, use the `_sort` query parameter with this format:

`1

 _sort={{yourFieldName}} {{asc/desc}} {{latitudeValue}},{{longitudeValue}} km

`

See an example

`1

 _sort=address.location asc -23.01227,-43.46163 km

`

When Master Data order results by distance from a geocoordinate field a new field is available: `_sort`. This field could be added in `_fields` parameter to retrieve the distance between the geocoordinate in the sort query.

## Real complete example

JSON Schema:

`1

 {

2

 "properties": {

3

 "name": {

4

 "type": "string"

5

 },

6

 "isActive": {

7

 "type": "boolean"

8

 },

9

 "address": {

10

 "type": "object",

11

 "properties": {

12

 "state": {

13

 "type": "string"

14

 },

15

 "location": {

16

 "type": [

17

 "null",

18

 "object"

19

 ],

20

 "properties": {

21

 "latitude": {

22

 "type": "number"

23

 },

24

 "longitude": {

25

 "type": "number"

26

 }

27

 },

28

 "additionalProperties": false

29

 }

30

 }

31

 }

32

 },

33

 "v-indexed": [

34

 "name",

35

 "isActive",

36

 "address"

37

 ],

38

 "v-default-fields": [

39

 "id",

40

 "name",

41

 "address",

42

 "_sort"

43

 ]

44

 }

`

Query:

`1

 /search?address.location=-23.01227,-43.46163,100km&_schema=v1&_sort=address.location asc -23.01227,-43.46163 km&_fields=id,_sort

`

Result:

`1

 [

2

 {

3

 "id": "AME",

4

 "_sort": [

5

 0

6

 ]

7

 },

8

 {

9

 "id": "BAR",

10

 "_sort": [

11

 10.71936198115181

12

 ]

13

 },

14

 {

15

 "id": "BAN",

16

 "_sort": [

17

 14.87184710662879

18

 ]

19

 },

20

 {

21

 "id": "BRX",

22

 "_sort": [

23

 27.607623540300178

24

 ]

25

 }

26

 ]

`

Contributors

1

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

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/Master-Data/master-data-v2/searching-by-geocoordinates-in-master-data-v2.md)

[Using dynamic expressions on Master Data v2« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2//docs/guides/using-dynamic-expressions-on-master-data-v2)[Setting up alternate keys in Master Data v2Next »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2//docs/guides/setting-up-alternate-keys-in-master-data-v2)

Contributors

1

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

ON THIS PAGE

[Saving documents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2%23saving-documents)

[Filtering](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2%23filtering)

[Ordering search results by distance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2%23ordering-search-results-by-distance)

[Real complete example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2%23real-complete-example)

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/Master-Data/master-data-v2/searching-by-geocoordinates-in-master-data-v2.md)

Copy page

On this page

ON THIS PAGE

[Saving documents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2%23saving-documents)

[Filtering](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2%23filtering)

[Ordering search results by distance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2%23ordering-search-results-by-distance)

[Real complete example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/searching-by-geocoordinates-in-master-data-v2/docs/guides/searching-by-geocoordinates-in-master-data-v2%23real-complete-example)

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 4 configuringtemplates 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-4-configuringtemplates/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/docs/guides/getting-started-with-storefront-solutions)

---

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

---

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

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

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

[1\. Setting up your development environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-1-basicsetup)

[2\. Configuring your account](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-2-prerequesites)

[3\. Creating a Store Theme project](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-3-settingyourstoretheme)

[4\. Configuring templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates)

[5\. Defining styles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-5-definingstyles)

[6\. Building your own store theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-6-buildingyourownstoretheme)

[7\. Making your store theme public](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-making-your-theme-content-public)

[Glossary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/store-framework-glossary)

Concepts

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

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

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

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

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/docs/guides/vtex-io-multi-language-stores)

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

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides)

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

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

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

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

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

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/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-4-configuringtemplates/docs/guides/getting-started-with-storefront-solutions)

---

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

---

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

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

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

[1\. Setting up your development environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-1-basicsetup)

[2\. Configuring your account](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-2-prerequesites)

[3\. Creating a Store Theme project](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-3-settingyourstoretheme)

[4\. Configuring templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates)

[5\. Defining styles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-5-definingstyles)

[6\. Building your own store theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-6-buildingyourownstoretheme)

[7\. Making your store theme public](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-making-your-theme-content-public)

[Glossary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/store-framework-glossary)

Concepts

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

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

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

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

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/docs/guides/vtex-io-multi-language-stores)

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

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/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-4-configuringtemplates/docs/guides/storefront-best-practices)

---

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

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

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

[4\. Configuring templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates)

4\. Configuring templates

Learn how to manage templates and customize your Store Theme.

In this guide, you'll learn how to customize your store theme by managing templates that define the structure of your website pages. Templates declare `JSON` blocks that, once rendered, determine the set of components for your website pages, such as the homepage, product page, search results page, etc.

The [Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-theme) app already implements basic templates for each page of your store, defined within its `blocks.json` or `blocks.jsonc` files. These templates enable your store to display VTEX Store Framework default components, even if you haven’t made any custom configurations in the code. By managing templates, you can create a custom theme for your website by adding or removing blocks to meet your business needs.

## Before you begin

### Learn about the JSON block concept

Familiarize yourself with the concept of a `JSON` block - the smallest Store Framework abstraction of React components displayed on the user interface. Thus, blocks are self-contained pieces of code, exported to the platform by independent apps, that determine how components are rendered on your website.

Blocks are imbued with higher flexibility, allowing you to achieve complex scenarios and specific component behaviors by configuring their properties (_props_) or even declaring them in other blocks. In practice, when you edit your theme's code using the Store Theme app, you're directly modifying blocks that will become your store's page components when rendered.

> To add a new component to a page, you simply declare a new block in the corresponding template. Similarly, removing a block from a template will exclude its associated component from the page.

### Get to know the property (prop) concept

To manage your templates efficiently, be familiar with the concept of `properties` (_prop_), which define the performance and visual identity of the component rendered in the interface. The more props a block has, the more flexible its configuration becomes for the end user.

Every JSON is defined using `{ }`, with keys and values that together specify its properties, representing its inherent characteristics. See the example below:

`1

{

2

 "name": "Pedro",

3

 "height": 1.90

4

}

`

In the example above, `name` and `height` are the object's keys, and their respective values are `Pedro` and `1.90`.

The `key + value` pair constitutes the property (or _prop_) of the JSON, defining its essential characteristics.

> The key and value can also be called, respectively, property name and property value.

### Understand the block composition

When a block is being developed, the composition definition indicates how the block’s content is structured or how it interacts with other components. There are 3 types of composition definitions:

* `blocks`: Have a fixed position on the store’s page irrespective of where they were declared in the code, leading to a preordained position on the UI.
* `children`: Do not have a fixed position on the store’s page, which means that how they’re declared in the code directly impacts the page position. The `children` block declared first will be at the top of the page, followed by the second one below it, and so on.
* `slots`: Placeholders within a block that enable the insertion of dynamic content. It is useful for flexible component design where content can be passed into specific slots, enabling the customization or reuse of a block with different content.

According to their composition, the listed blocks will determine whether they should be declared in the parent block's `blocks` list or in its `children` list when building a single component on the UI.

> You can find out which composition a block has by looking at its code in the exporting app's `interfaces.json` file.

## Instructions

### Step 1 - Declaring blocks in your Store Theme app

Declare all your blocks in the `blocks.jsonc` file, or create as many files and folders as needed within the `store` folder to organize store blocks and templates. You can also declare blocks in the `blocks` subfolder. The only difference is that `jsonc` files allow you to add comments to the code.

Since blocks are pieces of code exported by VTEX Store Framework apps, whenever a block is used in your theme, the app behind it must be declared in your Store Theme [dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-dependencies/) list.

The `dependencies` object within the `manifest.json` file of your Store Theme app specifies the names and versions of various apps. These apps are pre-listed, as the default Store Theme code already defines templates that use blocks exported by them.

When declaring a new block in your Store Theme app, check if the app blocking it is listed as a dependency. If not, open the `manifest.json` file and add the app name and desired version to the `dependencies` list, following this format: `"vtex.{appName}": "{majorVersion}.x"`.

> Replace the values between the curly braces based on your scenario.

### Step 2 - Managing blocks in your theme

To better understand how to manage blocks within your Store Theme app, follow the steps below to see the structure of the predefined homepage template:

1. Open the Store Theme app using the code editor of your choice.
2. Go to `store` and then `blocks`.
3. Access `home` and then `home.jsonc`. You'll see a result similar to the following:

`` 1

{

2

 "store.home": {

3

 "blocks": [

4

 "list-context.image-list#demo",

5

 /* You can make references to blocks defined in other files.

6

 * For example, `flex-layout.row#deals` is defined in the `deals.json` file. */

7

 "flex-layout.row#deals",

8

 "rich-text#shelf-title",

9

 "flex-layout.row#shelf",

10

 "info-card#home",

11

 "rich-text#question",

12

 "rich-text#link",

13

 "newsletter"

14

 ]

15

 },

16

17

 "shelf#home": {

18

 "blocks": ["product-summary.shelf"]

19

 },

20

21

 "product-summary.shelf": {

22

 "children": [

23

 "product-summary-name",

24

 "product-summary-description",

25

 "product-summary-image",

26

 "product-summary-price",

27

 "product-summary-sku-selector",

28

 "product-summary-buy-button"

29

 ]

30

 },

31

32

 "list-context.image-list#demo": {

33

 "children": ["slider-layout#demo-images"],

34

 "props": {

35

 "height": 720,

36

 "images": [

37

 {

38

 "image": "https://storecomponents.vteximg.com.br/arquivos/banner-principal.png",

39

 "mobileImage": "https://storecomponents.vteximg.com.br/arquivos/banner-principal-mobile.jpg"

40

 },

41

 {

42

 "image": "https://storecomponents.vteximg.com.br/arquivos/banner.jpg",

43

 "mobileImage": "https://storecomponents.vteximg.com.br/arquivos/banner-principal-mobile.jpg"

44

 }

45

 ]

46

 }

47

 },

48

 "slider-layout#demo-images": {

49

 "props": {

50

 "itemsPerPage": {

51

 "desktop": 1,

52

 "tablet": 1,

53

 "phone": 1

54

 },

55

 "infinite": true,

56

 "showNavigationArrows": "desktopOnly",

57

 "blockClass": "carousel"

58

 }

59

 },

60

61

 "rich-text#shelf-title": {

62

 "props": {

63

 "text": "## Summer",

64

 "blockClass": "shelfTitle"

65

 }

66

 },

67

 "flex-layout.row#shelf": {

68

 "children": ["list-context.product-list#demo1"]

69

 },

70

 "list-context.product-list#demo1": {

71

 "blocks": ["product-summary.shelf"],

72

 "children": ["slider-layout#demo-products"],

73

 "props": {

74

 "orderBy": "OrderByTopSaleDESC"

75

 }

76

 },

77

 "slider-layout#demo-products": {

78

 "props": {

79

 "itemsPerPage": {

80

 "desktop": 5,

81

 "tablet": 3,

82

 "phone": 1

83

 },

84

 "infinite": true,

85

 "fullWidth": true,

86

 "blockClass": "shelf"

87

 }

88

 },

89

90

 "info-card#home": {

91

 "props": {

92

 "id": "info-card-home",

93

 "isFullModeStyle": false,

94

 "textPosition": "left",

95

 "imageUrl": "https://storecomponents.vteximg.com.br/arquivos/banner-infocard2.png",

96

 "headline": "Clearance Sale",

97

 "callToActionText": "DISCOVER",

98

 "callToActionUrl": "/sale/d",

99

 "blockClass": "info-card-home",

100

 "textAlignment": "center"

101

 }

102

 },

103

104

 "rich-text#question": {

105

 "props": {

106

 "text": "**This is an example store built using the VTEX platform.\nWant to know more?**",

107

 "blockClass": "question"

108

 }

109

 },

110

111

 "rich-text#link": {

112

 "props": {

113

 "text": "\n**Reach us at**\nwww.vtex.com.br",

114

 "blockClass": "link"

115

 }

116

 },

117

118

 "product-summary-buy-button": {

119

 "props": {

120

 "displayBuyButton": "displayButtonAlways"

121

 }

122

 }

123

}

 ``

As you can see above, the default `store.home` homepage template declares the following blocks:

* `list-context.image-list#demo`
* `flex-layout.row#deals`
* `rich-text#shelf-title`
* `flex-layout.row#shelf`
* `info-card#home`
* `rich-text#question`
* `rich-text#link`
* `newsletter`

This means that your default store homepage will comprise the components defined by these blocks.

To build more complex components, the `home.jsonc` file includes each block’s declaration and configuration, using the block's props and, if necessary, other blocks.

> More than simply declaring a block in the block list template, you must also define its behavior when rendered as a component. To do this, use the block's props, as shown in the [Clarifying block naming and properties](#step-3-clarifying-block-naming-and-properties) section, and include other child blocks to configure it, as detailed in [Defining blocks composition](#step-4-defining-blocks-composition).

### Step 3 - Clarifying block naming and properties

Still in the `home.jsonc` file, use `ctrl+f` and search for the `rich-text#question` block. This block renders a component that displays markdown text to users.

`1

"rich-text#question": {

2

 "props": {

3

 "text": "**This is an example store built using the VTEX platform. Want to know more?**",

4

 "blockClass": "question"

5

 }

6

},

`

The `rich-text#question` block has two props: `text` and `blockClass`. The `text` prop specifies the content the component will display, while `blockClass` defines an ID used for customization.

To check the available props of the app behind the `rich-text` block, see the Configuration section within the [Rich Text](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-rich-text) app documentation. Note that the exported block's name is simply `rich-text`, whereas Store Theme uses `rich-text#block`. This is because you can use a `#` symbol after the block's official name to easily identify it when inserting it into the theme's code and better organize the theme.

> All the props available to configure a block can be found in the documentation of its exporting app or in the block's own documentation (if applicable).

### Step 4 - Defining blocks composition

Still in the `home.jsonc`, search for the`shelf#home` block.

`1

"shelf#home": {

2

 "blocks": ["product-summary.shelf"]

3

},

`

Note that it declares another block to your `blocks` list, which in turn declares other blocks below in a list called `children`:

`1

"product-summary.shelf": {

2

 "children": [

3

 "product-summary-name",

4

 "product-summary-description",

5

 "product-summary-image",

6

 "product-summary-price",

7

 "product-summary-sku-selector",

8

 "product-summary-buy-button"

9

 ]

10

},

`

In the example above, `product-summary.shelf` requires other blocks as children, such as `product-summary-name`, to render the component properly.

> As previously mentioned, a component can be a crossroad for multiple blocks. Therefore, one of your theme blocks may need to list other blocks to achieve the desired rendering on the UI.

To build a component using multiple blocks, the main block can declare a `blocks` list, such as `shelf#home`, or a `children` list, as seen in the `product-summary.shelf` block.

As explained in [Understand the block composition](#understand-the-block-composition), the choice between using a `blocks` or `children` list depends on the _composition_ of the blocks being declared.

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/_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-4-configuringtemplates/_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/Getting-Started/getting-started-3/vtex-io-documentation-4-configuringtemplates.md)

[3\. Creating a Store Theme project« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates//docs/guides/vtex-io-documentation-3-settingyourstoretheme)[5\. Defining stylesNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates//docs/guides/vtex-io-documentation-5-definingstyles)

Contributors

2

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

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23before-you-begin)

[Learn about the JSON block concept](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23learn-about-the-json-block-concept)[Get to know the property (prop) concept](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23get-to-know-the-property-prop-concept)[Understand the block composition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23understand-the-block-composition)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23instructions)

[Step 1 - Declaring blocks in your Store Theme app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23step-1-declaring-blocks-in-your-store-theme-app)[Step 2 - Managing blocks in your theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23step-2-managing-blocks-in-your-theme)[Step 3 - Clarifying block naming and properties](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23step-3-clarifying-block-naming-and-properties)[Step 4 - Defining blocks composition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23step-4-defining-blocks-composition)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Getting-Started/getting-started-3/vtex-io-documentation-4-configuringtemplates.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-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23before-you-begin)

[Learn about the JSON block concept](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23learn-about-the-json-block-concept)[Get to know the property (prop) concept](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23get-to-know-the-property-prop-concept)[Understand the block composition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23understand-the-block-composition)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23instructions)

[Step 1 - Declaring blocks in your Store Theme app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23step-1-declaring-blocks-in-your-store-theme-app)[Step 2 - Managing blocks in your theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23step-2-managing-blocks-in-your-theme)[Step 3 - Clarifying block naming and properties](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23step-3-clarifying-block-naming-and-properties)[Step 4 - Defining blocks composition](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-4-configuringtemplates/docs/guides/vtex-io-documentation-4-configuringtemplates%23step-4-defining-blocks-composition)

On this page

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


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

[User] How do I use the VTEX store media 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-media/docs/guides)

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

VTEX IO Apps

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

---

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

---

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

[Availability Notify](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.availability-notify)

[Category Menu](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.category-menu)

[Kit Look](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexbr.kitlook)

[Icon Pack list](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.store-icons/iconpack)

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

[Live Shopping](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexventures.livestreaming)

[PayPal Checkout with Smart Payment Buttons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.connector-paypal-commerce-platform)

[Personal Shopper](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexventures.personal-shopper-free)

[Product Availability](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.product-availability)

[Product Comparison](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.product-comparison)

[Product Gifts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.product-gifts)

[Product Highlight by VTEX Segment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexarg.product-highlight-by-vtex-segment)

[Product Specification Badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.product-specification-badges)

[Quantity On Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexarg.quantity-on-cart)

[Reviews and Ratings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.reviews-and-ratings)

[Querying personal MasterData Information with SafeData](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.safedata)

[Seller Selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.seller-selector)

[Similar Products Variants](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.similar-products-variants)

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

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

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

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

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

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

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

[VTEX IO Sandbox Component](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.sandbox)

[Shipping Option Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.shipping-option-components)

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

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

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

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

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

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

---

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

VTEX IO Apps

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

---

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

---

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

[Availability Notify](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.availability-notify)

[Category Menu](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.category-menu)

[Kit Look](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexbr.kitlook)

[Icon Pack list](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.store-icons/iconpack)

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

[Live Shopping](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexventures.livestreaming)

[PayPal Checkout with Smart Payment Buttons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.connector-paypal-commerce-platform)

[Personal Shopper](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexventures.personal-shopper-free)

[Product Availability](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.product-availability)

[Product Comparison](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.product-comparison)

[Product Gifts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.product-gifts)

[Product Highlight by VTEX Segment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexarg.product-highlight-by-vtex-segment)

[Product Specification Badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.product-specification-badges)

[Quantity On Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtexarg.quantity-on-cart)

[Reviews and Ratings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.reviews-and-ratings)

[Querying personal MasterData Information with SafeData](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.safedata)

[Seller Selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.seller-selector)

[Similar Products Variants](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.similar-products-variants)

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

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

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

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

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

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

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

[VTEX IO Sandbox Component](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.sandbox)

[Shipping Option Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.shipping-option-components)

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

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

Media

Official extension

Version: 0.3.0

Latest version: 0.3.0

[![{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAABCAIAAAB2XpiaAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAFUlEQVR4nGPg4+Mz1Nfjl5T7f2c+AAzxA3lptuDWAAAAAElFTkSuQmCC","img":{"src":"https://img.shields.io/badge/all_contributors-0-orange.svg?style=flat-square","width":110,"height":20,"type":"svg"}}](https://read.calvincode.net/reader?url=https://img.shields.io/badge/all_contributors-0-orange.svg?style=flat-square)](#contributors-)

The Media app allows you to display image and video assets using a single block.

![{"base64":"  ","img":{"width":600,"height":295,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":1317006,"url":"https://user-images.githubusercontent.com/8127610/107076678-848fbf80-67ca-11eb-9ba3-8a7d285c4b2c.gif"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/8127610/107076678-848fbf80-67ca-11eb-9ba3-8a7d285c4b2c.gif)

## Configuration

1. Add the `store-media` app to your theme's dependencies in the `manifest.json` file:

`1

 "dependencies ": {

2

+ "vtex.store-media": "0.x"

3

 }

`

Now, you are able to use all blocks exported by the `store-media` app. Check out the full list below:

| Block name              | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| media                   | This block is capable of displaying a single image or video.                                                                                |
| list-context.media-list | This block allows you to display a list of images and videos in your store with a higher degree of composability. You can use it along with other list-context or slider-layout blocks to create different sliders and layouts. |

### `media` block

The `media` block inherits all props from `image` and `video` blocks. It's highly recommended you check out the docs for [Image](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/store-image) and [Video](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/store-video) blocks before using this block.

You can use props from both blocks, but `media` will only consider the props from the block (`image` or `video`) that matches the current `mediaType`, or, in the case of `mediaType` being `imageOrVideo`, that matches the type of the `src`.

| Prop name | Type | Description                                                                                | Default value |
| --------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| mediaType | enum | Type of the media to be displayed. Possible values are: image (behaves as an image block no matter the src), video (behaves as an video block no matter the src), and imageOrVideo. Choosing imageOrVideo will make media automatically identify the type of the src based on its extension and behave accordingly. | imageOrVideo  |

Use the **admin's Site Editor** to manage some props declared in the `media` block. Using the Site Editor to provide the image or video `src` will force you to choose between `image` and `video`.

**Usage Example**:

`1

"media#mobile-phone": {

2

 "props": {

3

 "src": "https://storecomponents.vteximg.com.br/arquivos/mobile-phone.png",

4

 "blockClass": "storePrint"

5

 }

6

}

`

### `list-context.media-list` block

The `list-context.media-list` block acts just like the `list-context.image-list` block and inherits a lot from `image` and `video` blocks, with a few key differences. It's highly recommended you check out the docs for [Image](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/store-image) and [Video](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/store-video) blocks before using this block.

`list-context.media-list` accepts both images and videos, so you can mix them inside a single carousel, for example. Images can receive `image` blocks' props and videos can receive `video` blocks' props. If you pass props that don't match the media type, they will be ignored.

| Prop name | Type                 | Description                                                                         | Default value                                                                         |
| --------- | -------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| height    | \`string             | number\`                                                                            | This value is used for the max-height CSS property and **is applied to images only**. |
| mediaList | \[MediaListElement\] | List of MediaListElement that represents the media to be added to the list context. | \[\]                                                                                |

* `MediaListElement` object

A `MediaListElement` object has a very similar shape to the props accepted by the `media` component, that is, you can specify the `mediaType` of the asset you want to display and pass the props for `image` and `video` blocks. Read the docs for the `media` block to better understand how that works.

Differently from the `media` component, it does **not** use the `src` prop to receive the assets. For images, it uses the `image` and `mobileImage` props, and, for video, it uses the `video` and `mobileVideo` props.

| Prop name   | Type   | Description                                                                                | Default value |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | ------------- |
| image       | string | URL to the image to be displayed.                                                                                | undefined     |
| mobileImage | string | URL to the image to be displayed when the user is using a mobile device. If it's undefined, image will be used instead. | undefined     |
| video       | string | URL to the video to be displayed.                                                                                | undefined     |
| mobileVideo | string | URL to the video to be displayed when the user is using a mobile device. If it's undefined, video will be used instead. | undefined     |

**Usage Example**:

`1

"list-context.media-list#demo": {

2

 "children": ["slider-layout#demo-media"],

3

 "props": {

4

 "height": 720,

5

 "mediaList": [

6

 {

7

 "image": "https://storecomponents.vteximg.com.br/arquivos/banner-principal.png",

8

 "mobileImage": "https://storecomponents.vteximg.com.br/arquivos/banner-principal-mobile.jpg"

9

 },

10

 {

11

 "video": "https://www.youtube.com/embed/JgkrlaF52WQ"

12

 },

13

 {

14

 "image": "https://storecomponents.vteximg.com.br/arquivos/banner.jpg",

15

 "mobileImage": "https://storecomponents.vteximg.com.br/arquivos/banner-principal-mobile.jpg"

16

 }

17

 ]

18

 }

19

},

20

"slider-layout#demo-media": {

21

 "props": {

22

 "itemsPerPage": 1,

23

 "infinite": true,

24

 "showNavigationArrows": "desktopOnly",

25

 "blockClass": "carousel"

26

 }

27

}

`

## Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://read.calvincode.net/reader?url=https://vtex.io/docs/recipes/style/using-css-handles-for-store-customization).

Just like they do with props, all blocks from this app inherits all of `image` and `video` blocks' CSS Handles. You can find them in their respective docs.

Keep in mind that, for instance, applying CSS customizations to CSS Handles that came from `image` won't have any effect if the `mediaType` is set to `video` or if the `mediaType` is set to `imageOrVideo` and the `src` was identified as a video.

[Store Link« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.store-link)[Store NewsletterNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.store-newsletter)

See also

[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-media/docs/apps/vtex.store-media%23configuration)

[media block](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.store-media%23media-block)[list-context.media-list block](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.store-media%23list-contextmedia-list-block)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-media/docs/apps/vtex.store-media%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=)