The store locator component displays an experience where your website's users can browse a list of locations, find the nearest one, and view details.
While store locations are the most common use case, you can use this component to show many nearby points of interest like parks, ATMs, or gas stations.
To use <gmpx-store-locator>, pass it a JavaScript array containing the
locations you want to present. Each location, called a listing, is defined as
an object with the following properties:
interface StoreLocatorListing {
// Name of the location or store
title: string;
// Address lines, used when displaying the list.
addressLines?: string[];
// Geographic coordinates of the location
position: LatLng|LatLngLiteral;
// Place ID for this location, used to retrieve additional details
placeId?: string;
// Optional list of additional actions to display with each location
actions?: StoreLocatorAction[];
}
interface StoreLocatorAction {
// Button label for this action
label: string;
// URI that will be opened in a new tab
defaultUri?: string;
}
See below for a full example.
When loading the library with a <script> tag (referencing the CDN bundle), please refer to the instructions in the root-level Readme. You do not need to take additional steps to use this component.
When bundling your dependencies and you want to include <gmpx-store-locator> on a page:
import '@googlemaps/extended-component-library/store_locator.js';
When bundling your dependencies and you need to access the class StoreLocator directly (less common):
import { StoreLocator } from '@googlemaps/extended-component-library/store_locator.js';
| Attribute | Property | Property type | Description | Default | Reflects? |
|---|---|---|---|---|---|
feature-set |
featureSet |
FeatureSet |
Chooses the capabilities of this store locator: * 'basic' shows a list of locations with pins on a map.* 'intermediate' adds a search input so users can find the location closest to them.* 'advanced' brings in a Place details view to show photos, hours, and reviews for each location. |
✅ | |
map-id |
mapId |
string | undefined |
The Map ID of the map. See the Map ID documentation for more information. | ✅ | |
listings |
StoreLocatorListing[] | undefined |
List of locations to display in the store locator. | ❌ | ||
mapOptions |
Partial<google.maps.MapOptions> | undefined |
Overrides for the map options. Provide values for center and zoom to display a map when listings is empty. |
{ mapTypeControl: false, maxZoom: 17, streetViewControl: false } |
❌ |
Configures the Store Locator component from data generated by the Quick Builder tool in the Maps Console.
Parameters:
| Name | Optional? | Type | Description |
|---|---|---|---|
configuration |
QuickBuilderConfiguration |
The configuration object generated by the Quick Builder tool. |
You can use most built-in CSS properties to control the positioning or display of this component, similar to a <span> or <div> element. The component also supports the following styling inputs for more customization:
| Name | Default | Description |
|---|---|---|
--gmpx-color-surface |
#fff |
Background color. 🌎 |
--gmpx-color-on-surface |
#212121 |
Main text color. 🌎 |
--gmpx-color-on-surface-variant |
#757575 |
Color of less important text such as captions. 🌎 |
--gmpx-color-primary |
#1976d2 |
Color of buttons and icons. 🌎 |
--gmpx-color-outline |
#e0e0e0 |
Button outline and divider color. 🌎 |
--gmpx-fixed-panel-width-row-layout |
28.5em |
Controls the side panel width when the component is displayed in row direction. The map width will adjust automatically to fill remaining space. |
--gmpx-fixed-panel-height-column-layout |
65% |
Controls the side panel height when the component is displayed in column direction. The map height will adjust automatically to fill remaining space. |
--gmpx-font-family-base |
'Google Sans Text', sans-serif |
Font family for regular text. 🌎 |
--gmpx-font-family-headings |
--gmpx-font-family-base |
Font family for headings. 🌎 |
--gmpx-font-size-base |
0.875rem |
Text size, sets scale for the component. 🌎 |
--gmpx-hours-color-open |
#188038 |
Opening hours text color when the place is open (advanced feature set only). |
--gmpx-hours-color-closed |
#d50000 |
Opening hours text color when the place is closed (advanced feature set only). |
--gmpx-rating-color |
#ffb300 |
Color of star rating icons in the details view (advanced feature set only). |
--gmpx-rating-color-empty |
#e0e0e0 |
Background color of star rating icons in the details view (advanced feature set only). |
🌎 indicates a global style token shared by multiple components. Please see the library Readme for more information.
Start by adding a store locator component to your page's HTML. If you haven't already, add an API loader to initialize the Maps JavaScript SDK.
<gmpx-api-loader key="MY_API_KEY"></gmpx-api-loader>
<gmpx-store-locator map-id="DEMO_MAP_ID"></gmpx-store-locator>Next, use JavaScript to configure a list of park locations. This could be in a short <script> tag or part of your website's JS bundle:
document.addEventListener('DOMContentLoaded', () => {
const locator = document.querySelector('gmpx-store-locator');
locator.listings = [
{
title: 'Bryce Canyon National Park',
addressLines: ['Utah', 'USA'],
position: {'lat': 37.6404, 'lng': -112.1696},
placeId: 'ChIJLevDAsZrNYcRBm2svvvY6Ws',
actions: [{
label: 'Website',
defaultUri:
'https://www.nps.gov/brca/index.htm'
}]
},
{
title: 'Everglades National Park',
addressLines: ['Florida', 'USA'],
position: {'lat': 25.3952, 'lng': -80.5831},
placeId: 'ChIJ2wVsejCo0IgRlzEvdlY-4A8',
actions: [{
label: 'Website',
defaultUri:
'https://www.nps.gov/ever/index.htm'
}]
}
];
});Finally, use CSS to customize the size and appearance of the store locator:
gmpx-store-locator {
width: 100%;
height: 40em;
--gmpx-color-surface: #fdfaf2;
--gmpx-color-on-surface: ##355034;
--gmpx-color-on-surface-variant: #8f8f8f;
--gmpx-color-primary: #3f7843;
--gmpx-font-family-base: "Times", serif;
--gmpx-font-family-headings: "Roboto", sans-serif;
}In addition to the Maps JavaScript API, this component relies on the following Google Maps Platform APIs which may incur cost and must be enabled.
Used to display a map.
Adding a map to your website with Web Components
This component uses the Places API in two ways:
- Places Autocomplete to help an end user specify their location (intermediate and advanced feature sets only).
- Place Details to view more information about a selected listing (advanced feature set only).
- Autocomplete search for the end user's location (intermediate and advanced feature sets only):
- Places API Autocomplete documentation.
- Fetching Places data for the "view details" panel (advanced feature set only):
- Place class documentation
- Displaying Places photos (advanced feature set only): Photos documentation
Please be sure to check this documentation for additional requirements and recommendations regarding your use.
- SKU: Autocomplete (included with Place Details) – Per Session
- SKU: Find Place (fallback query)
- SKU: Place Details
- SKU: Basic Data
- SKU: Contact Data
- SKU: Atmosphere Data
- SKU: Place Photo
Used to display a route from the end user's location to the selected listing, advanced feature set only.
Directions API documentation. Please be sure to check this documentation for additional requirements and recommendations regarding your use.
Used to sort and display travel times from the end user's location. Intermediate and advanced feature sets only.