TypeScript and Google Maps

  • TypeScript can enhance Google Maps development by providing static typing and improved code maintainability.

  • Use the @types/google.maps package from DefinitelyTyped for TypeScript support in your Google Maps projects.

  • Alpha and beta Google Maps features may require type casting to avoid TypeScript errors.

  • In case of conflicting type definitions, consider utilizing the skipLibCheck compiler option to bypass type checking of external libraries.

  • When necessary, configure typeRoots in your TypeScript configuration to ensure proper inclusion of Google Maps type definitions.

TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. The sample code below demonstrates simple usage of Google Maps using TypeScript:

TypeScript

async function init(): Promise<void> {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map')!;
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();

JavaScript

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();

CSS

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

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>

    <body>
        <gmp-map center="-34.397,150.644" zoom="8" map-id="DEMO_MAP_ID">
        </gmp-map>
    </body>
</html>
View example

Get started

The DefinitelyTyped project is an open source project that maintains type declaration files for many packages including Google Maps. Use NPM to install the Google Maps JavaScript declaration files from the @types/google.maps package:

npm i -D @types/google.maps

For more information, see source files on GitHub.

Conflicting @types packages

Some libraries may use a package other than @types/google.maps, which may cause conflicts. Use the skipLibCheck compiler option to avoid issues with inconsistent types:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Specify typeRoots

Some frameworks such as Angular may require specifying the typeRoots compiler option to include types installed from @types/google.maps and all other @types packages.

By default all visible @types packages are included in your compilation. Packages in node_modules/@types of any enclosing folder are considered visible:

{
  "compilerOptions": {
    "typeRoots": [
      "node_modules/@types"
    ]
  }
}