VTEX Developer Portal

All ContributorsAll Contributors

The Store Locator app fetches the Pickup point data in order to display address location for retail stores.

store-liststore-list
store-detailstore-detail

Configuration

  1. Install the Store Locator app in your VTEX account by running vtex install vtex.store-locator in your terminal.
  2. In your account's admin page, select Inventory&Shipping section and then acess Settings.
  3. Type in the Google Geolocation API key and save your changes.
  4. Open your Store Theme app directory in your code editor.
  5. Add the Store Locator app as a peerDependency in the manifest.json file:
 "peerDependencies": {
+  "vtex.store-locator": "0.x"
 }

Once installed, the app will generate a new route called /stores for your store, listing the retail stores registered in the Pickup points section (under the Inventory & shipping module).

The new page already contains a default template with all blocks exported by the Store Locator app, meaning that the /stores page is ready to be rendered and no further actions are required. However, you can customize the new page overwriting the template by creating a brand new one as you wish. To do so, check the Advanced configurations section below.

This app will also add a new entry to your store's /sitemap.xml file in order to have all the pickup points available to the search engines - make sure you already have the [email protected] app installed in your VTEX account!

Advanced configuration

In order to define the Store Locator custom page UI, you must use the blocks exported by the vtex.store-locator app. Namely, they are:

Block nameDescription
store-listRenders a list of retail stores and a map with all their localization.
store-groupProvides the pickup point data to other blocks exported by the app, such as the ones listed below.
store-nameRenders the store name.
store-back-linkRenders a link to return to the previous page.
store-mapRenders a map with the retail store localization.
store-addressRenders the store's address.
store-hoursRenders the store's opening hours. This information comes by default from the Pickup Points configuration, but you can also define manually through the Store's theme
store-instructionsRenders the desired instructions to access the retail store.
  1. Open your Store Theme app directory in your code editor.
  2. In the store/blocks folder of your Store Theme app, create a new file called storelocator.json.
  3. Create a new store template in it called store.storelocator. In its blocks array, paste the default implementation stated below:
{
  "store.storelocator": {
    "blocks": ["flex-layout.row#title", "flex-layout.row#container"]
  },
  "flex-layout.row#title": {
    "children": ["flex-layout.col#title"]
  },
  "flex-layout.row#container": {
    "children": ["store-list"]
  },
  "flex-layout.col#title": {
    "children": ["rich-text#title"],
    "props": {
      "blockClass": "title",
      "preventVerticalStretch": true
    }
  },
  "rich-text#title": {
    "props": {
      "text": "## Store Locator"
    }
  },
  "store.storedetail": {
    "blocks": ["flex-layout.row#titleStore", "store-group"]
  },
  "store-group": {
    "children": ["flex-layout.row#containerStore"],
    "props": {
      "title": "{storeName} Store"
    }
  },
  "flex-layout.row#titleStore": {
    "children": ["flex-layout.col#titleStore"]
  },
  "flex-layout.row#containerStore": {
    "children": ["flex-layout.col#detail", "flex-layout.col#store"]
  },
  "flex-layout.col#titleStore": {
    "children": ["rich-text#titleStore"],
    "props": {
      "blockClass": "title",
      "preventVerticalStretch": true
    }
  },
  "rich-text#titleStore": {
    "props": {
      "text": "## Store Detail"
    }
  },
  "flex-layout.col#detail": {
    "children": [
      "store-back-link",
      "store-map",
      "store-address",
      "store-hours",
      "store-instructions"
    ],
    "props": {
      "width": "30%",
      "preventVerticalStretch": true
    }
  },
  "flex-layout.col#store": {
    "children": ["store-name"],
    "props": {
      "width": "70%"
    }
  },
  "store-hours": {
    "props": {
      "label": "Business hours:",
      "format": "12h",
      "businessHours": [
        {
          "dayOfWeek": "Sunday",
          "openingTime": "11:00am",
          "closingTime": "5:00pm"
        },
        {
          "dayOfWeek": "Monday",
          "openingTime": "11:00am",
          "closingTime": "6:00pm"
        },
        {
          "dayOfWeek": "Tuesday",
          "openingTime": "11:00am",
          "closingTime": "6:00pm"
        },
        {
          "dayOfWeek": "Wednesday",
          "openingTime": "11:00am",
          "closingTime": "6:00pm"
        },
        {
          "dayOfWeek": "Thursday",
          "openingTime": "11:00am",
          "closingTime": "6:00pm"
        },
        {
          "dayOfWeek": "Friday",
          "openingTime": "11:00am",
          "closingTime": "6:00pm"
        },
        {
          "dayOfWeek": "Saturday",
          "openingTime": "11:00am",
          "closingTime": "5:00pm"
        }
      ]
    }
  },
  "store-back-link": {
    "props": {
      "label": "Back to all stores"
    }
  },
  "store-instructions": {
    "props": {
      "label": ""
    }
  }
}
  1. Configure each one of the blocks previously declared as you wish using their props (check out the following tables).

store-list

Prop nameTypeDescriptionDefault value
filterByTagstringDesired tags to filter the Pickup Points fetched and displayed. You canundefined
iconstringIcon URL (svg or png) to be displayed alongside with the store-list blocks.Google's default.
iconWidthnumberIcon width in pixels (px).Image default width.
iconHeightnumberIcon height in pixels (px).Image default height.
zoomnumberMap zoom as number.10
longnumberLongitude to be used as coordenates.null
latnumberLattitude to be used as coordenates.null

ℹ️ If you have all your pick up points as in seller accounts you should provide long and lat props to show all seller stores - if you don't have this props and you neither have pick up points the app will not show nothing.

store-group props

Prop nameTypeDescriptionDefault value
titlestringTitle text to be displayed on the store page. Use {storeName}, {storeCity}, or {storeState} as value to display the store's accurate data on the UI.{storeName}
descriptionstringPage description used in the page's Structured Data for SEO purposes. The {storeName}, {storeCity}, or {storeState} variables can be used in the description text.``
imageSelectorstringCSS Selector that will wrap all the images displayed on the UI.undefined
instructionsAsPhonebooleanTo provide a unique phone number for each store, a phone number can be entered in the Instructions field in the Pickup Points section. The store-instructions will display a phone number and it will be included in the page's Structured Data.false

Both imageSelector and instructionsAsPhone must be declared with valid values in order to provide Structured Data for SEO purposes.

store-name props

Prop nameTypeDescriptionDefault value
textstringText to be displayed alongside with the store name. Use {storeName}, {storeCity}, or {storeState} as value to display the store's accurate data on the UI.
tagstringHTML element to wrap the store-name block when rendered on the UI.div

store-back-link props

Prop nameTypeDescriptionDefault value
labelstringEntitles the store-back-link block when rendered on the UI.Back to all stores

store-map props

Prop nameTypeDescriptionDefault value
widthstringMap width in pixels (px).100%
heightstringMap height in pixels (px).200px
zoomintegerMap zoom as number14

store-address props

Prop nameTypeDescriptionDefault value
labelstringEntitles the store-address block when rendered on the UI.Store address

store-hours props

Prop nameTypeDescriptionDefault value.
labelstringEntitles the store-hours block when rendered on the UI.Store hours
formatenumHour format. Possible values are : 12h and 24h.24h
businessHoursarray of objectformat {"dayOfWeek": "Sunday","openingTime": "11:00am","closingTime": "5:00pm"}undefined

store-description props

Prop nameTypeDescriptionDefault value
textstringText to be displayed on the store page. Use {storeName}, {storeCity}, or {storeState} within your text to display that store's specific value.

store-instructions props

Prop nameTypeDescriptionDefault value
labelstringEntitles the store-instructions block when rendered on the UI.Information

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.

CSS Handles
addressContainer
addressLabel
addressListFirstItem
addressListItem
addressListLink
addressList
addressStoreAddress
addressStoreName
addressStoreAddressGroupA
addressStoreAddressNumber
addressStoreAddressStreet
backlinkContainer
backlink
businessHours
container
descriptionContainer
descriptionText
dayOfWeek
divider
hourRow
hoursContainer
hoursLabel
instructionsContainer
instructionsLabel
instructionsText
listingMapContainer
loadAll
markerInfoAddress
markerInfoLink
markerInfoStoreName
markerInfo
noResults
storeName
storesListCol
storesList
storesMapCol

Contributors ✨

Thanks goes to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind are welcome!

Updated 11 days ago


Store Locator


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.