Add a Google Map to a Web Page

  • This documentation explains how to embed a Google map into a webpage using HTML, CSS, and JavaScript.

  • You can add a map using a custom HTML element (gmp-map) or a standard div element, both requiring a Google Maps API key.

  • The process involves loading the Maps JavaScript API, adding the map to your HTML, and initializing it with coordinates and zoom level using JavaScript.

  • Code examples in HTML, CSS, and JavaScript (including TypeScript) are provided for both methods, demonstrating the implementation steps.

You can add a Google map to a web page using HTML, CSS, and JavaScript code. This page shows how to add a map to a web page, and then programmatically access the map instance.

Overview

To load a map, your web page must do the following things:

  • Load the Maps JavaScript API using a bootstrap loader. This is where your API key is passed. It can be added to either the HTML or JavaScript source files.
  • Add the map to the HTML page, and add the needed CSS styles.
  • Load the maps library and initialize the map.

Add a map using a gmp-map element

The gmp-map element is the preferred way to add a Google map to a web page. It is a custom HTML element created using web components. To add a map to a web page using a gmp-map element, take the following steps.

  1. Add a script element containing the bootstrap to an HTML page, or add it to a JavaScript or TypeScript source file without the script element. Configure the bootstrap with your API key and any other options. You can choose either dynamic library import or direct script loading. This example shows adding the direct script loading bootstrap to an HTML page:

    <script
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=maps,marker"
    defer
></script>

    Learn more about loading the Google Maps JavaScript API

  2. On the HTML page, add a gmp-map element. Specify latitude and longitude coordinates for center (required), a zoom value for zoom (required), and a map-id if needed (it is required for some features like Advanced Markers). The CSS height attribute is required for the map to be visible. It can be specified in either the HTML or CSS. In this example the height style attribute is specified in the HTML for simplicity.

    <gmp-map
  center="37.4220656,-122.0840897"
  zoom="10"
  map-id="DEMO_MAP_ID"
  style="height: 400px"
></gmp-map>
    index.html

Complete example code

<html>
  <head>
    <title>Add a Map using HTML</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <gmp-map
      center="37.4220656,-122.0840897"
      zoom="10"
      map-id="DEMO_MAP_ID"
      style="height: 400px"
    ></gmp-map>
   <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8&libraries=maps,marker&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Add a map using a div element (legacy) and JavaScript

To add a map to a web page using a div element, take the following steps.

  1. Add a script element containing the bootstrap to an HTML page, or add it to a JavaScript or TypeScript source file without the script element. Configure the bootstrap with your API key and any other options. You can choose either dynamic library import or direct script loading. This example shows adding the dynamic bootstrap to an HTML page:

    <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

    Learn more about loading the Google Maps JavaScript API

  2. On the HTML page, add a div element to contain the map.

    <div id="map"></div>

  3. In the CSS, set the map height to 100%. The CSS height attribute is required for the map to be visible.

    #map {
  height: 100%;
}

  4. In the JavaScript file, create a function to load the maps library and initialize the map. Specify latitude and longitude coordinates for center, and the zoom level to use for zoom. If needed, add a map ID using the map-id property.

    let map;
async function initMap() {
    const { Map } = await google.maps.importLibrary("maps");
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}
initMap();
    index.js

Complete example code

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;
async function initMap() {
    const { Map } = await google.maps.importLibrary("maps");
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}
initMap();
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

style.css

HTML

<html>
  <head>
    <title>Simple Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
  </body>
</html>
index.html

Try Sample

Set and get properties on the map instance

To interact with the map instance, select the containing element. The code to do this will vary depending on whether you used the gmp-map element or a div element.

Get a map instance from a gmp-map element

To get the map instance when using a gmp-map element, use document.querySelector to retrieve a mapElement instance, as shown here.

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;

Then set properties on the mapElement instance:

mapElement.zoom = 8;

The MapElement class uses the Map class internally; access the Map class using the MapElement.innerMap property, as shown here:

mapElement.innerMap.setOptions({
    mapTypeControl: false,
});

Get a map instance from a div element

When using a div element, get the map instance and set options at initialization time:

map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
    mapTypeControl: false,
});

After initialization, set options on the map instance as shown here:

map.setOptions({
    zoom: 8,
});