@googlemaps/js-api-loader
Advanced tools
Wrapper for the loading of Google Maps JavaScript API script in the browser
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.
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
});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.
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.
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 the @googlemaps/js-api-loader NPM package with:
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 users need to install the following types package.
npm i -D @types/google.maps
The reference documentation can be found at this link. The Google Maps JavaScript API documentation is the authoritative source for the loader options.
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.
Contributions are welcome and encouraged! If you'd like to contribute, send us a pull request and refer to our code of conduct and contributing guide.
This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform Terms of Service.
This library is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (e.g. Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to the code in this library.
This library is offered via an open source license. It is not governed by the Google Maps Platform Support [Technical Support Services Guidelines, the SLA, or the Deprecation Policy. However, any Google Maps Platform services used by the library remain subject to the Google Maps Platform Terms of Service.
This library adheres to semantic versioning to indicate when backwards-incompatible changes are introduced. Accordingly, while the library is in version 0.x, backwards-incompatible changes may be introduced at any time.
If you find a bug, or have a feature request, please file an issue on GitHub. If you would like to get answers to technical questions from other Google Maps Platform developers, ask through one of our developer community channels. If you'd like to contribute, please check the contributing guide.
You can also discuss this library on our Discord server.
FAQs
Wrapper for the loading of Google Maps JavaScript API script in the browser
The npm package @googlemaps/js-api-loader receives a total of 1,806,248 weekly downloads. As such, @googlemaps/js-api-loader popularity was classified as popular.
We found that @googlemaps/js-api-loader demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.