The Libraries type specifies which Google Maps JavaScript API libraries to load. Different libraries provide access to different features like drawing tools, places autocomplete, and visualizations.
Type Definition
import type { Library } from '@googlemaps/js-api-loader'
type Libraries = Library[]
Library type is imported from @googlemaps/js-api-loader and represents a single Google Maps library name.
Import
import type { Libraries } from '@react-google-maps/api'
Available Libraries
The following libraries are available in the Google Maps JavaScript API:
Provides access to the Places API for location search, autocomplete, and place details.Required for:
AutocompleteStandaloneSearchBox- Places service
Enables drawing tools for shapes like polygons, circles, rectangles, and polylines.Required for:
DrawingManager- Drawing tools
Provides utility functions for geometric calculations like distance, area, and containment.Required for:
- Distance calculations
- Area calculations
- Heading calculations
- Polygon/polyline utilities
Enables data visualization layers like heatmaps.Required for:
HeatmapLayer- Data visualization
Provides local context information for places.Required for: Advanced marker library for the new marker features.Required for:
- Advanced marker functionality
Usage
With LoadScript
import { LoadScript } from '@react-google-maps/api'
import type { Libraries } from '@react-google-maps/api'
const libraries: Libraries = ['places', 'drawing']
function App() {
return (
<LoadScript
googleMapsApiKey="YOUR_API_KEY"
libraries={libraries}
>
{/* Your map components */}
</LoadScript>
)
}
With useJsApiLoader
import { useJsApiLoader } from '@react-google-maps/api'
import type { Libraries } from '@react-google-maps/api'
const libraries: Libraries = ['places', 'visualization']
function MyComponent() {
const { isLoaded } = useJsApiLoader({
googleMapsApiKey: 'YOUR_API_KEY',
libraries,
})
if (!isLoaded) return <div>Loading...</div>
return <GoogleMap>{/* ... */}</GoogleMap>
}
Examples
Single Library
const libraries: Libraries = ['places']
<LoadScript
googleMapsApiKey="YOUR_API_KEY"
libraries={libraries}
>
<GoogleMap>
<Autocomplete>
<input type="text" placeholder="Search location" />
</Autocomplete>
</GoogleMap>
</LoadScript>
Multiple Libraries
const libraries: Libraries = ['places', 'drawing', 'visualization']
<LoadScript
googleMapsApiKey="YOUR_API_KEY"
libraries={libraries}
>
<GoogleMap>
<DrawingManager />
<HeatmapLayer data={heatmapData} />
<Autocomplete>
<input type="text" />
</Autocomplete>
</GoogleMap>
</LoadScript>
Conditional Libraries
import type { Libraries } from '@react-google-maps/api'
function useMapLibraries(enableDrawing: boolean, enablePlaces: boolean): Libraries {
const libraries: Libraries = []
if (enableDrawing) libraries.push('drawing')
if (enablePlaces) libraries.push('places')
return libraries
}
function App() {
const libraries = useMapLibraries(true, true)
const { isLoaded } = useJsApiLoader({
googleMapsApiKey: 'YOUR_API_KEY',
libraries,
})
// ...
}
Important Notes
The libraries array should be defined outside of the component or memoized to prevent unnecessary re-renders. Creating a new array on each render will cause the Google Maps API to reload.
Good Practice
// Define outside component
const libraries: Libraries = ['places', 'drawing']
function App() {
return (
<LoadScript libraries={libraries}>
{/* ... */}
</LoadScript>
)
}
Or with useMemo
import { useMemo } from 'react'
function App() {
const libraries = useMemo<Libraries>(() => ['places', 'drawing'], [])
return (
<LoadScript libraries={libraries}>
{/* ... */}
</LoadScript>
)
}
Bad Practice
function App() {
// Don't do this - creates new array every render
return (
<LoadScript libraries={['places', 'drawing']}>
{/* ... */}
</LoadScript>
)
}
Error Handling
If you use a component that requires a specific library without including it in the libraries array, you’ll get a console error:
// Missing 'drawing' library
const libraries: Libraries = ['places']
<LoadScript libraries={libraries}>
<GoogleMap>
{/* This will cause an error */}
<DrawingManager />
</GoogleMap>
</LoadScript>
Did you include prop libraries={['drawing']} in the URL?
To fix this, add the required library:
const libraries: Libraries = ['places', 'drawing']
TypeScript Benefits
Using the Libraries type provides type safety and autocomplete:
import type { Libraries } from '@react-google-maps/api'
// TypeScript will suggest valid library names
const libraries: Libraries = [
'places', // ✓ Valid
'drawing', // ✓ Valid
'invalid', // ✗ TypeScript error
]
