Skip to main content

​
Overview

useJsApiLoader is a React hook that loads the Google Maps JavaScript API using the official @googlemaps/js-api-loader package. This is the recommended approach for loading the Google Maps API in modern applications.

​
Signature

function useJsApiLoader(options: UseLoadScriptOptions): {
  isLoaded: boolean;
  loadError: Error | undefined;
}

​
Parameters

​
options
UseLoadScriptOptions
required
Configuration options for loading the Google Maps API.
​
googleMapsApiKey
string
required
Your Google Maps API key. Required for authentication.
​
id
string
default:"'script-loader'"
The ID attribute for the script element.
​
version
string
default:"'weekly'"
The version of the Google Maps API to load. Can be ‘weekly’, ‘quarterly’, ‘beta’, or a specific version number.
​
libraries
Library[]
default:"['maps']"
Array of Google Maps libraries to load. Available libraries include:
  • 'maps' - Core maps library
  • 'places' - Places library
  • 'geometry' - Geometry library
  • 'drawing' - Drawing library
  • 'visualization' - Visualization library
  • 'marker' - Advanced markers
​
language
string
default:"'en'"
The language to use for UI elements and display of labels on map tiles.
​
region
string
default:"'US'"
The region code to use for biasing geocoding results and map behavior.
​
mapIds
string[]
default:"[]"
Array of map IDs for use with advanced styling and features.
​
nonce
string
default:"''"
A nonce value for Content Security Policy (CSP) compliance.
​
authReferrerPolicy
'origin'
default:"'origin'"
Specifies the referrer policy for API requests.
​
preventGoogleFontsLoading
boolean
When true, prevents Google Maps from loading Google Fonts automatically.

​
Return Value

​
isLoaded
boolean
Indicates whether the Google Maps API has finished loading successfully.
​
loadError
Error | undefined
Contains any error that occurred during loading, or undefined if no error occurred.

​
Usage Example

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

function MyMapComponent() {
  const { isLoaded, loadError } = useJsApiLoader({
    googleMapsApiKey: 'YOUR_API_KEY',
    libraries: ['places', 'geometry'],
    version: 'weekly',
    language: 'en',
    region: 'US'
  });

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

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

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

​
With Multiple Libraries

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

// Define libraries outside component to avoid re-renders
const libraries: Libraries = ['places', 'drawing', 'geometry'];

function MapWithLibraries() {
  const { isLoaded, loadError } = useJsApiLoader({
    googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!,
    libraries,
  });

  if (!isLoaded) return <div>Loading...</div>;
  
  return <div>{/* Your map */}</div>;
}

​
Notes

  • Performance Warning: Keep the libraries array as a static constant outside your component. Passing a new array on each render will cause the API to reload, which impacts performance.
  • Loader Instance: This hook uses the official @googlemaps/js-api-loader package internally, which provides better performance and reliability.
  • Default Values: The hook applies sensible defaults (language: ‘en’, region: ‘US’, libraries: [‘maps’]).
  • Error Handling: Always check both isLoaded and loadError to handle loading states properly.

Build docs developers (and LLMs) love

Get started for freeTalk to us