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 access 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 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. To do so, check the Advanced configuration section below.

ℹ️

This app will also add a new entry to your store's /sitemap.xml file so that all your pickup points are available to 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 locations marked.
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's location.
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
filterByTagstringFilter fetched Pickup Points by this tag.undefined
iconstringIcon used to display store location in map. Input icon URL (svg or png).Google's default
iconWidthnumberIcon width in pixels (px).Image default width
iconHeightnumberIcon height in pixels (px).Image default height
zoomnumberMap zoom as a number.10
latnumberLatitude coordinate.undefined
longnumberLongitude coordinate.undefined
sortBystringProperty (name or distance) used to sort the stores list.distance

ℹ️

Use the lat and long props to display Pickup Points configured in seller accounts. If these props are not configured and you do not have any pick up points set up in your main account, the app will display no stores.

ℹ️

The filterByTag prop cannot be used along with lat and long. If you set a value for filterByTag, the lat and long props will be ignored.

store-group props

Prop nameTypeDescriptionDefault value
titlestringTitle used in the page's HTML title tag and Structured Data for SEO purposes. The {storeName}, {storeCity}, and / or {storeState} variables can be used in the title text.{storeName}
descriptionstringDescription text used in the page's HTML description meta tag and Structured Data for SEO purposes. The {storeName}, {storeCity}, and / or {storeState} variables can be used in the description text.empty string
imageSelectorstringCSS Selector to select the images included in the page's Structured Data.empty string
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 as store name. {storeName}, {storeCity}, and / or {storeState} values can be used to generate the store name.undefined
tagstringHTML element to wrap the store-name block when rendered on the UI.div

store-back-link props

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

store-map props

Prop nameTypeDescriptionDefault value
widthstringMap width.100%
heightstringMap height.200px
zoomintegerMap zoom as a number14
iconstringIcon used to display store location in map. Input icon URL (svg or png).undefined

store-address props

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

store-hours props

Prop nameTypeDescriptionDefault value.
labelstringLabel for 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.undefined

store-instructions props

Prop nameTypeDescriptionDefault value
labelstringLabel for 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!


Did this page help you?