@googlemaps/js-api-loader

What is @googlemaps/js-api-loader?

The @googlemaps/js-api-loader package is a lightweight JavaScript library that simplifies the loading of the Google Maps JavaScript API into web pages. It provides a promise-based API to load the Google Maps API dynamically, handling the insertion of the script tag and optional configuration settings.

What are @googlemaps/js-api-loader's main functionalities?

Loading the Google Maps JavaScript API

This code sample demonstrates how to load the Google Maps JavaScript API using the @googlemaps/js-api-loader. It initializes a new Loader instance with an API key, version, and additional libraries, then loads the API and creates a map instance.

const { Loader } = require('@googlemaps/js-api-loader');

const loader = new Loader({
  apiKey: 'YOUR_API_KEY',
  version: 'weekly',
  libraries: ['places']
});

loader.load().then(() => {
  const map = new google.maps.Map(document.getElementById('map'), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8
  });
});

Setting additional configuration options

This code sample shows how to set additional configuration options such as language and region when loading the Google Maps JavaScript API.

const loader = new Loader({
  apiKey: 'YOUR_API_KEY',
  version: 'weekly',
  libraries: ['places'],
  language: 'en',
  region: 'US'
});

loader.load().then(() => {
  // Google Maps API is ready to use
});

Other packages similar to @googlemaps/js-api-loader

google-maps

The 'google-maps' npm package is another library for loading the Google Maps API. It is similar to @googlemaps/js-api-loader but has a different API design and may not be as up-to-date with the latest Google Maps API features.

load-google-maps-api

The 'load-google-maps-api' package is an alternative to @googlemaps/js-api-loader. It provides a function to load the Google Maps API, but it might not offer the same level of configuration and error handling as @googlemaps/js-api-loader.

README

Google Maps JavaScript API Loader

Description

Load the Google Maps JavaScript API script dynamically. This takes inspiration from the google-maps npm package but updates it with ES6, Promises, and TypeScript.

Install

Available via npm as the package @googlemaps/js-api-loader.

npm i @googlemaps/js-api-loader

Alternatively you may add the umd package directly to the html document using the unpkg link.

<script src="https://unpkg.com/@googlemaps/js-api-loader@1.x/dist/index.min.js"></script>

When adding via unpkg, the loader can be accessed at google.maps.plugins.loader.Loader.

TypeScript

TypeScript users need to install the following types package.

npm i -D @types/google.maps

Documentation

The reference documentation can be found at this link. The Google Maps JavaScript API documentation is the authoritative source for the loader options.

Example

import { Loader } from '@googlemaps/js-api-loader';

const loader = new Loader({
  apiKey: "",
  version: "weekly",
  libraries: ["places"]
});

const mapOptions = {
  center: {
    lat: 0,
    lng: 0
  },
  zoom: 4
};

Using a promise for a specific library.

// Promise for a specific library
loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
  });

Using a promise for when the script has loaded.

// Promise
loader
  .load()
  .then((google) => {
    new google.maps.Map(document.getElementById("map"), mapOptions);
  })
  .catch(e => {
    // do something
  });

Alternatively, if you want to use a callback.

// Callback
loader.loadCallback(e => {
  if (e) {
    console.log(e);
  } else {
    new google.maps.Map(document.getElementById("map"), mapOptions);
  }
});

View the package in action here.

Support

This library is community supported. We're comfortable enough with the stability and features of the library that we want you to build real production applications on it.

If you find a bug, or have a feature suggestion, please log an issue. If you'd like to contribute, please read How to Contribute.

Changelog

1.16.3 (2024-02-15)

Bug Fixes

• add loading=async to the urls with callbacks (#822) (2d05217)