reviews Get a Maps Demo Key: Try out select Maps JavaScript API and Places UI Kit features at no cost with a Maps Demo Key—no billing information required.

TypeScript and Google Maps Stay organized with collections Save and categorize content based on your preferences.

Page Summary

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();index.ts

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();index.js

CSS

/* 
 * 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>
        <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>index.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.

Add `google.maps` to the `tsconfig` `types` option

If your tsconfig file sets the types compiler option, TypeScript includes only the @types packages listed in that array. Installing @types/google.maps isn't enough to enable TypeScript support for Google Maps, and code that uses the google namespace fails to compile with the following error:

Error T2503: Cannot find namespace 'google'.

To add google.maps to the types array:

{
  "compilerOptions": {
    "types": ["google.maps"]
  }
}

Alternatively, add the following directive to a declaration file that your project includes, such as vite-env.d.ts:

/// <reference types="google.maps" />

For more information, see types.

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"
    ]
  }
}