Web Components in the Maps JavaScript API (Preview)

Web Components are a popular W3C standard that encapsulate HTML, CSS, and JS in custom and reusable HTML elements. These reusable components can range from atomic pieces of functionality, like displaying the star rating for a place, to more complex business logic. This guide describes Web Components available in Maps JavaScript API.

For more information about the standard itself, see Web Components.

Audience

This documentation is designed to let you quickly start exploring and developing applications with Web Components. You should be familiar with HTML and CSS programming concepts.

Display a Map

The easiest way to start learning about Web Components is to see an example. The following example displays a map of the San Jose area.

a map of the San Jose area

HTML

<html>
  <head>
    <title>Simple Map</title>
    <link rel="stylesheet" type="text/css" href="style.css" />

    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=maps,marker&v=beta">
    </script>

    <script>
      function initMap() {
        console.log('Maps JavaScript API loaded.');
      }
    </script>

  </head>
  <body>
    <gmp-map center="37.4220656,-122.0840897" zoom="10" map-id="DEMO_MAP_ID"></gmp-map>
  </body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

In this example there are a few things to note:

  1. The Maps JavaScript API is called asynchronously. The callback function is used to know when the API has loaded.
  2. Presentation of the map is defined with the <gmp-map> custom element.
  3. Map properties are defined by specifying attributes in the <gmp-map> custom element.
  4. Styling can be applied inline to custom elements or declared in a separate CSS file.

Style the basemap

A map ID is an identifier associated with a specific map style or feature. To take advantage of optional cloud configuration features, replace the Cloud-based maps styling DEMO_MAP_ID with your own map ID. To learn how to create a map ID and configure a custom style, visit Cloud-based Maps Styling.

Add markers to the map

Just as one can nest built-in HTML tags to create complex content hierarchies, one can also nest <gmp-advanced-marker> inside an element to display one or more map markers.

map with markers

HTML

<html>
  <head>
    <title>Simple Map with Markers</title>
    <link rel="stylesheet" type="text/css" href="style.css" />

    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE&callback=initMap&libraries=maps,marker&v=beta">
    </script>

    <script>
      function initMap() {
        console.log('Maps JavaScript API loaded.');
      }
    </script>

  </head>
  <body>
    <gmp-map center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID">
      <gmp-advanced-marker position="37.4220656,-122.0840897" title="Mountain View, CA"></gmp-advanced-marker>
      <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA"></gmp-advanced-marker>
    </gmp-map>
  </body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

Here we've added two <gmp-advanced-marker> elements inside the <gmp-map> custom element. Text for title provides an additional hover text and accessibility label for the specified element.

JavaScript Events

A major benefit of Web Components is ease of use. With a few lines of code, one can display a Map with limited knowledge of JavaScript or advanced programming. Once implemented, the code follows the familiar patterns of other HTML elements. For example, one can use the native browser eventing system to react to Map or Advanced Marker actions, such as a marker click.

marker click event

HTML

<html>
<head>
  <title>Google Maps - Marker Click Example</title>
  <link rel="stylesheet" href="style.css" type="text/css">

  <script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE&callback=initMap&libraries=maps,marker&v=beta">
  </script>

  <script>
    function initMap() {
      console.log('Maps JavaScript API loaded.');

      const advancedMarkers = document.querySelectorAll("#marker-click-event-example gmp-advanced-marker");
      for (const advancedMarker of advancedMarkers) {
        customElements.whenDefined(advancedMarker.localName).then(async () => {
          advancedMarker.addEventListener('gmp-click', async () => {
            const {InfoWindow} = await google.maps.importLibrary("maps");
            const infoWindow = new InfoWindow({
              content: advancedMarker.title
            });
            infoWindow.open({
              anchor: advancedMarker
            });
          });
        });
      }
    }
  </script>
</head>
<body>

<gmp-map id="marker-click-event-example" center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID">
  <gmp-advanced-marker position="37.4220656,-122.0840897" title="Mountain View, CA"></gmp-advanced-marker>
  <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA"></gmp-advanced-marker>
</gmp-map>

</body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

In this example, initMap represents the required callback function once the Maps JavaScript API loads completely. The code establishes listeners to each marker and presents an info window when each marker is clicked.

What's next