Skip to main content
Before you can use any Google Maps components, you need to load the Google Maps JavaScript API. This library provides two approaches for loading the API: useJsApiLoader hook and LoadScript component. The useJsApiLoader hook is the recommended approach for loading the Google Maps API. It uses the modern @googlemaps/js-api-loader package and provides better control over the loading state.

​
Basic Usage

import { useJsApiLoader } from '@react-google-maps/api';

function App() {
  const { isLoaded, loadError } = useJsApiLoader({
    googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY,
    libraries: ['places', 'geometry'],
  });

  if (loadError) {
    return <div>Error loading maps</div>;
  }

  if (!isLoaded) {
    return <div>Loading maps</div>;
  }

  return (
    <GoogleMap
      mapContainerStyle={{ width: '100%', height: '400px' }}
      center={{ lat: -34.397, lng: 150.644 }}
      zoom={8}
    >
      {/* Your map components */}
    </GoogleMap>
  );
}

​
Configuration Options

The useJsApiLoader hook accepts the following options:
​
googleMapsApiKey
string
required
Your Google Maps API key. Get one from the Google Cloud Console.
​
libraries
Library[]
default:"['maps']"
Array of Google Maps libraries to load. Available libraries include:
  • places - Places API for search and autocomplete
  • geometry - Geometry library for calculations
  • drawing - Drawing tools
  • visualization - Data visualization (heatmaps)
  • marker - Advanced marker features
​
version
string
default:"'weekly'"
Version of the Google Maps API to load. Can be 'weekly', 'quarterly', or a specific version number.
​
language
string
default:"'en'"
Language for map labels and controls.
​
region
string
default:"'US'"
Region biasing for geocoding and place searches.
​
mapIds
string[]
Array of Map IDs for styling with Google Cloud-based maps styling.
​
preventGoogleFontsLoading
boolean
Prevents Google Maps from loading Google Fonts (Roboto).
​
authReferrerPolicy
'origin'
Referrer policy for API requests.
​
id
string
default:"'script-loader'"
ID for the injected script tag.
​
nonce
string
Nonce for Content Security Policy.

​
Return Value

The hook returns an object with:
  • isLoaded (boolean) - true when the API is fully loaded
  • loadError (Error | undefined) - Error object if loading failed

​
Advanced Example

import { useJsApiLoader } from '@react-google-maps/api';

const libraries: Library[] = ['places', 'geometry', 'drawing'];

function MapApplication() {
  const { isLoaded, loadError } = useJsApiLoader({
    googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!,
    libraries,
    version: 'weekly',
    language: 'en',
    region: 'US',
    mapIds: ['YOUR_MAP_ID'],
    preventGoogleFontsLoading: true,
  });

  if (loadError) {
    console.error('Error loading Google Maps:', loadError);
    return <div>Map cannot be loaded right now, sorry.</div>;
  }

  return isLoaded ? <MapComponent /> : <Spinner />;
}
Performance Tip: Keep the libraries array as a constant outside your component or use a static class property. Creating a new array on every render will trigger performance warnings and unnecessary reloads.

​
LoadScript Component

The LoadScript component is an alternative approach that wraps your application and loads the API. It provides a component-based API with loading states.

​
Basic Usage

import { LoadScript, GoogleMap } from '@react-google-maps/api';

const libraries = ['places', 'geometry'];

function App() {
  return (
    <LoadScript
      googleMapsApiKey={process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY}
      libraries={libraries}
      loadingElement={<div>Loading...</div>}
    >
      <GoogleMap
        mapContainerStyle={{ width: '100%', height: '400px' }}
        center={{ lat: -34.397, lng: 150.644 }}
        zoom={8}
      />
    </LoadScript>
  );
}

​
LoadScript Props

​
googleMapsApiKey
string
required
Your Google Maps API key.
​
libraries
Library[]
Array of libraries to load.
​
loadingElement
ReactNode
Custom loading component to display while the API loads.
​
onLoad
() => void
Callback fired when the API is loaded.
​
onError
(error: Error) => void
Callback fired if loading fails.
​
onUnmount
() => void
Callback fired when the component unmounts.
​
preventGoogleFontsLoading
boolean
Prevents loading of Google Fonts.
​
id
string
default:"'script-loader'"
ID for the script tag.
​
version
string
default:"'weekly'"
API version to load.
​
language
string
Language code.
​
region
string
Region code.

​
Complete Example

import { LoadScript, GoogleMap } from '@react-google-maps/api';
import { useState } from 'react';

const libraries = ['places'];

function App() {
  const [scriptLoaded, setScriptLoaded] = useState(false);

  return (
    <LoadScript
      googleMapsApiKey={process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!}
      libraries={libraries}
      version="weekly"
      language="en"
      region="US"
      loadingElement={<div>Loading Maps...</div>}
      onLoad={() => {
        console.log('Google Maps API loaded');
        setScriptLoaded(true);
      }}
      onError={(error) => {
        console.error('Error loading Google Maps:', error);
      }}
      preventGoogleFontsLoading={true}
    >
      <div style={{ height: '100vh' }}>
        <GoogleMap
          mapContainerStyle={{ width: '100%', height: '100%' }}
          center={{ lat: 40.7128, lng: -74.0060 }}
          zoom={12}
        />
      </div>
    </LoadScript>
  );
}

​
Comparison: useJsApiLoader vs LoadScript

Advantages:
  • Modern hook-based API
  • Better for functional components
  • More explicit control flow
  • Uses official @googlemaps/js-api-loader
  • Lighter weight
Best for:
  • New projects
  • Functional components
  • Next.js and modern React frameworks

​
Performance Best Practices

Avoid Creating New Library Arrays: Do not create the libraries array inline in your component. This causes the API to reload on every render.
// ❌ Bad - Creates new array on every render
function App() {
  const { isLoaded } = useJsApiLoader({
    googleMapsApiKey: 'YOUR_KEY',
    libraries: ['places', 'geometry'], // New array every render!
  });
}

// ✅ Good - Stable reference
const libraries = ['places', 'geometry'];

function App() {
  const { isLoaded } = useJsApiLoader({
    googleMapsApiKey: 'YOUR_KEY',
    libraries, // Stable reference
  });
}
The library will warn you in the console if it detects the libraries prop changing:
Performance warning! LoadScript has been reloaded unintentionally! You should not pass libraries prop as new array.

​
Error Handling

Always handle loading errors gracefully: 
function App() {
  const { isLoaded, loadError } = useJsApiLoader({
    googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY,
  });

  if (loadError) {
    return (
      <div>
        <h1>Error Loading Maps</h1>
        <p>{loadError.message}</p>
        <button onClick={() => window.location.reload()}>
          Retry
        </button>
      </div>
    );
  }

  if (!isLoaded) {
    return <LoadingSpinner />;
  }

  return <MapComponent />;
}

​
Next Steps

GoogleMap Component

Learn how to use the GoogleMap component

TypeScript Support

Explore TypeScript types and interfaces

Build docs developers (and LLMs) love

Get started for freeTalk to us