@googlemaps/js-api-loader, @react-google-maps/api, google-maps-api-loader, google-maps-react, and react-google-maps are npm packages that help developers integrate Google Maps into web applications. These libraries handle loading the Google Maps JavaScript API, managing script injection, and providing React components or utilities to render maps, markers, and other map features. While some focus on low-level API loading, others offer high-level React abstractions.
Google Maps Integration in React: A Practical Guide to Modern Libraries
Integrating Google Maps into a React app seems straightforward — until you deal with script loading, lifecycle mismatches, memory leaks, and API versioning. The ecosystem offers several packages, but not all are equal in quality, maintenance, or developer experience. Let’s cut through the noise and compare the real options available today.
🚫 Deprecated Packages: What Not to Use
Two packages on this list are officially deprecated and should be avoided in new projects:
google-maps-react: Archived on GitHub, last published in 2019, and marked as deprecated on npm. No support for React 18+ concurrent features.react-google-maps: Also archived, with the author explicitly recommending migration to@react-google-maps/api. Suffers from outdated patterns like class components and manual DOM manipulation.
If you’re maintaining a legacy app using either, plan a migration. Both lack security updates, TypeScript support, and compatibility with modern React.
🧱 Core Loading Utilities: Separating Concerns
Before rendering maps, you must load the Google Maps JavaScript API. Two packages focus solely on this task:
@googlemaps/js-api-loader (Official)
This is Google’s recommended way to load the Maps API dynamically. It returns a promise that resolves when the script is loaded and ready. Works in any JavaScript environment — React, Vue, or vanilla.
// Using @googlemaps/js-api-loader in a React component
import { Loader } from "@googlemaps/js-api-loader";
import { useEffect, useRef } from "react";
function Map() {
const mapRef = useRef(null);
useEffect(() => {
const loader = new Loader({
apiKey: "YOUR_API_KEY",
version: "weekly"
});
loader.load().then(() => {
const map = new google.maps.Map(mapRef.current, {
center: { lat: -34.397, lng: 150.644 },
zoom: 8
});
});
}, []);
return <div ref={mapRef} style={{ height: "400px" }} />;
}
Pros: Official, lightweight (~2KB), supports dynamic API loading, prevents duplicate script injection.
google-maps-api-loader (Unofficial)
A community alternative that predates Google’s official loader. It also returns a promise but lacks active maintenance and official backing.
// Using google-maps-api-loader
import loadGoogleMaps from "google-maps-api-loader";
loadGoogleMaps({
apiKey: "YOUR_API_KEY"
}).then(google => {
// Use google.maps here
});
While functional, there’s no reason to use this over @googlemaps/js-api-loader, which is better tested and officially supported.
🧩 React-Specific Abstractions: Declarative Mapping
For React apps, you’ll likely want components that manage the map lifecycle automatically. Only one package currently fits this role well:
@react-google-maps/api (Modern & Maintained)
This library wraps the Google Maps API in React components and hooks. It uses @googlemaps/js-api-loader under the hood and provides a declarative syntax.
// Using @react-google-maps/api
import { GoogleMap, Marker, useJsApiLoader } from "@react-google-maps/api";
const containerStyle = { width: "100%", height: "400px" };
const center = { lat: -34.397, lng: 150.644 };
function MyMap() {
const { isLoaded } = useJsApiLoader({
id: "google-map-script",
googleMapsApiKey: "YOUR_API_KEY"
});
return isLoaded ? (
<GoogleMap
mapContainerStyle={containerStyle}
center={center}
zoom={10}
>
<Marker position={center} />
</GoogleMap>
) : <div>Loading...</div>;
}
Key advantages:
- Full TypeScript support
- Automatic cleanup (no memory leaks)
- Hooks like
useLoadScriptanduseGoogleMap - Supports advanced features: drawing tools, heatmaps, street view
- Actively maintained with regular updates
🔍 Side-by-Side Feature Comparison
| Feature | @googlemaps/js-api-loader | @react-google-maps/api | google-maps-api-loader | google-maps-react | react-google-maps |
|---|---|---|---|---|---|
| Actively maintained | ✅ Yes (Google) | ✅ Yes | ❌ No | ❌ Deprecated | ❌ Deprecated |
| React components | ❌ No | ✅ Yes | ❌ No | ⚠️ Legacy | ⚠️ Legacy |
| TypeScript support | ✅ Yes | ✅ Yes | ❌ No | ❌ No | ❌ No |
| Automatic script loading | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| Prevents duplicate scripts | ✅ Yes | ✅ Yes | ⚠️ Partial | ⚠️ Partial | ⚠️ Partial |
| Memory leak protection | N/A | ✅ Yes | N/A | ❌ No | ❌ No |
🛠️ Real-World Decision Guide
Scenario 1: You’re using React and want simplicity
→ Use @react-google-maps/api. It handles everything: loading, rendering, cleanup, and provides intuitive components. Example for a store locator:
<GoogleMap center={userLocation} zoom={12}>
{stores.map(store => (
<Marker key={store.id} position={store.latLng} />
))}
</GoogleMap>
Scenario 2: You need fine-grained control or aren’t using React
→ Use @googlemaps/js-api-loader. Load the API once, then interact directly with google.maps objects. Ideal for performance-critical apps or when integrating with non-React UIs.
Scenario 3: You’re stuck with a legacy codebase
→ Migrate from react-google-maps or google-maps-react to @react-google-maps/api. The migration path is well-documented, and the new API is more predictable and less error-prone.
💡 Pro Tips
- Always use an API key and restrict it to your domain in the Google Cloud Console.
- Avoid inline script tags — they can cause duplicate API loads and race conditions. Use a loader package instead.
- Clean up event listeners if using raw
google.mapsobjects.@react-google-maps/apihandles this automatically. - Test loading states — network failures can leave your app hanging. Wrap loader promises in try/catch or use React error boundaries.
✅ Final Recommendation
For new React projects, @react-google-maps/api is the clear winner — it’s modern, safe, and productive. For non-React or minimal setups, reach for @googlemaps/js-api-loader. Avoid the deprecated packages entirely; they introduce technical debt with no upside.
The goal isn’t just to show a map — it’s to build something maintainable, performant, and resilient. Choose the tool that helps you do that without fighting the framework.
- @googlemaps/js-api-loader:
Choose
@googlemaps/js-api-loaderif you need a lightweight, official utility to load the Google Maps JavaScript API without any React-specific logic. It’s ideal for vanilla JavaScript projects or when you want full control over map rendering and lifecycle management in React using hooks likeuseEffect. This package is actively maintained by Google and avoids framework coupling. - @react-google-maps/api:
Choose
@react-google-maps/apiif you’re building a React application and want a modern, well-maintained library with declarative components, TypeScript support, and built-in hooks for interacting with the Google Maps API. It handles script loading internally and provides a clean React-friendly interface for maps, markers, info windows, and more. - react-google-maps:
Avoid
react-google-mapsin new projects. It is deprecated and unmaintained, with its GitHub repository archived and npm page indicating it’s no longer updated. The author recommends migrating to@react-google-maps/api, which is its spiritual successor with improved architecture and ongoing maintenance. - google-maps-react:
Avoid
google-maps-reactin new projects. It is deprecated and no longer maintained, as confirmed by its GitHub repository archive status and npm deprecation notice. Existing codebases should migrate to@react-google-maps/apifor continued support and modern React patterns. - google-maps-api-loader:
Choose
google-maps-api-loaderonly if you require a minimal, promise-based loader for the Google Maps API in non-React environments. However, note that this package is not officially maintained by Google and lacks React integration. For new projects, prefer@googlemaps/js-api-loaderwhich serves the same purpose but is officially supported.
Google Maps JavaScript API Loader
Description
Load the Google Maps JavaScript API script dynamically. This is an npm version of the Dynamic Library Import script.
Requirements
- Sign up with Google Maps Platform
- A Google Cloud Platform project with the Maps JavaScript API enabled
- An API key associated with the project above
Installation
Install @googlemaps/js-api-loader with:
npm install --save @googlemaps/js-api-loader
# or
yarn add @googlemaps/js-api-loader
# or
pnpm add @googlemaps/js-api-loader
TypeScript users should additionally install the types for the Google Maps JavaScript API:
npm install --save-dev @types/google.maps
Usage
import { setOptions, importLibrary } from "@googlemaps/js-api-loader";
// Set the options for loading the API.
setOptions({ key: "your-api-key-here" });
// Load the needed APIs.
// Note: once the returned promise is fulfilled, the libraries are also
// available in the global `google.maps` namespace.
const { Map } = await importLibrary("maps");
const map = new Map(mapEl, mapOptions);
// Alternatively:
await importLibrary("maps");
const map = new google.maps.Map(mapEl, mapOptions);
// Or, if you prefer using callbacks instead of async/await:
importLibrary("maps").then(({ Map }) => {
const map = new Map(mapEl, mapOptions);
});
If you use custom HTML elements from the Google Maps JavaScript API (e.g.
<gmp-map>, and <gmp-advanced-marker>), you need to import them as well.
Note that you do not need to await the result of importLibrary() in this case.
The custom elements will upgrade automatically once the library is loaded
and you can use the whenDefined() method to wait for the upgrade to
complete.
import { setOptions, importLibrary } from "@googlemaps/js-api-loader";
// Set the options for loading the API.
setOptions({ key: "your-api-key-here" });
// Start loading the libraries needed for custom elements.
importLibrary("maps"); // needed for <gmp-map>
importLibrary("marker"); // needed for <gmp-advanced-marker>
// Wait for gmp-map to be upgraded and interact with it.
await customElements.whenDefined("gmp-map");
const map = document.querySelector("gmp-map");
// ...
Documentation
This package exports just two functions, setOptions() and importLibrary().
// Using named exports:
import { setOptions, importLibrary } from "@googlemaps/js-api-loader";
setOptions({ key: GOOGLE_MAPS_API_KEY });
await importLibrary("core");
setOptions(options: APIOptions): void
Sets the options for loading the Google Maps JavaScript API and installs the
global google.maps.importLibrary() function that is used by the
importLibrary() function of this package.
This function should be called as early as possible in your application and should only be called once. Any further calls will not have any effect and log a warning to the console.
Below is a short summary of the accepted options, see the documentation for full descriptions and additional information:
key: string: Your API key. This is the only required option.v: string: The version of the Maps JavaScript API to load.language: string: The language to use.region: string: The region code to use.libraries: string[]: Additional libraries to preload.authReferrerPolicy: string: Set the referrer policy for the API requests.mapIds: string[]: An array of map IDs to preload.channel: string: Can be used to track your usage.solutionChannel: string: Used by the Google Maps Platform to track adoption and usage of examples and solutions.
importLibrary(library: string): Promise
Loads the specified library. Returns a promise that resolves with the library object when the library is loaded. In case of an error while loading the library (might be due to poor network conditions and other unforseeable circumstances), the promise is rejected with an error.
Calling this function for the first time will trigger loading the Google Maps JavaScript API itself.
The following libraries are available:
core:google.maps.CoreLibrarymaps:google.maps.MapsLibrarymaps3d:google.maps.Maps3DLibraryplaces:google.maps.PlacesLibrarygeocoding:google.maps.GeocodingLibraryroutes:google.maps.RoutesLibrarymarker:google.maps.MarkerLibrarygeometry:google.maps.GeometryLibraryelevation:google.maps.ElevationLibrarystreetView:google.maps.StreetViewLibraryjourneySharing:google.maps.JourneySharingLibraryvisualization:google.maps.VisualizationLibraryairQuality:google.maps.AirQualityLibraryaddressValidation:google.maps.AddressValidationLibrarydrawing:google.maps.DrawingLibrary(deprecated)
Migrating from v1 to v2
See the migration guide.
Contributing
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.
Terms of Service
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.
European Economic Area (EEA) developers
If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region. Learn more.
Support
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.
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.