GoogleMap
The GoogleMap component is the main component for rendering a Google Map in your React application. It provides a wrapper around the Google Maps JavaScript API and manages the map instance lifecycle.
Import
import { GoogleMap } from '@react-google-maps/api'
TypeScript Signature
function GoogleMap(props: GoogleMapProps): JSX.Element
type GoogleMapProps = {
children?: ReactNode | undefined
id?: string | undefined
mapContainerStyle?: CSSProperties | undefined
mapContainerClassName?: string | undefined
options?: google.maps.MapOptions | undefined
extraMapTypes?: google.maps.MapType[] | undefined
center?: google.maps.LatLng | google.maps.LatLngLiteral | undefined
clickableIcons?: boolean | undefined
heading?: number | undefined
mapTypeId?: string | undefined
streetView?: google.maps.StreetViewPanorama | undefined
tilt?: number | undefined
zoom?: number | undefined
onClick?: ((e: google.maps.MapMouseEvent) => void) | undefined
onDblClick?: ((e: google.maps.MapMouseEvent) => void) | undefined
onDrag?: (() => void) | undefined
onDragEnd?: (() => void) | undefined
onDragStart?: (() => void) | undefined
onMouseMove?: ((e: google.maps.MapMouseEvent) => void) | undefined
onMouseOut?: ((e: google.maps.MapMouseEvent) => void) | undefined
onMouseOver?: ((e: google.maps.MapMouseEvent) => void) | undefined
onMouseDown?: ((e: google.maps.MapMouseEvent) => void) | undefined
onMouseUp?: ((e: google.maps.MapMouseEvent) => void) | undefined
onRightClick?: ((e: google.maps.MapMouseEvent) => void) | undefined
onMapTypeIdChanged?: (() => void) | undefined
onTilesLoaded?: (() => void) | undefined
onBoundsChanged?: (() => void) | undefined
onCenterChanged?: (() => void) | undefined
onHeadingChanged?: (() => void) | undefined
onIdle?: (() => void) | undefined
onProjectionChanged?: (() => void) | undefined
onResize?: (() => void) | undefined
onTiltChanged?: (() => void) | undefined
onZoomChanged?: (() => void) | undefined
onLoad?: ((map: google.maps.Map) => void | Promise<void>) | undefined
onUnmount?: ((map: google.maps.Map) => void | Promise<void>) | undefined
}
Props
Container Props
Optional ID attribute for the map container div element.
Inline styles for the map container. Use this to set width and height.mapContainerStyle={{ width: '100%', height: '400px' }}
CSS class name for the map container div element.
Child components to render within the map context (Markers, Polylines, etc.).
Map Configuration Props
center
google.maps.LatLng | google.maps.LatLngLiteral
The initial map center position. Can be a LatLng object or literal.center={{ lat: 40.7128, lng: -74.0060 }}
The initial map zoom level. Valid values are 0 (world view) to 22+ (street level). The map type to display. Options include:
'roadmap' - Default road map view'satellite' - Satellite imagery'hybrid' - Satellite with road overlay'terrain' - Terrain with physical features
The heading for aerial imagery in degrees. Only applies to satellite and hybrid map types.
The angle of incidence for aerial imagery. Valid values are 0 (top-down) and 45 (perspective).
Whether POI (Point of Interest) icons are clickable.
streetView
google.maps.StreetViewPanorama
A StreetViewPanorama instance to bind to the map.
Additional custom map types to register with the map.
Mouse Event Handlers
onClick
(e: google.maps.MapMouseEvent) => void
Called when the map is clicked.onClick={(e) => {
console.log('Clicked at:', e.latLng?.lat(), e.latLng?.lng())
}}
onDblClick
(e: google.maps.MapMouseEvent) => void
Called when the map is double-clicked.
onRightClick
(e: google.maps.MapMouseEvent) => void
Called when the map is right-clicked.
onMouseMove
(e: google.maps.MapMouseEvent) => void
Called when the mouse moves over the map.
onMouseOver
(e: google.maps.MapMouseEvent) => void
Called when the mouse enters the map.
onMouseOut
(e: google.maps.MapMouseEvent) => void
Called when the mouse leaves the map.
onMouseDown
(e: google.maps.MapMouseEvent) => void
Called when a mouse button is pressed on the map.
onMouseUp
(e: google.maps.MapMouseEvent) => void
Called when a mouse button is released on the map.
Drag Event Handlers
Called repeatedly while the user drags the map.
Called when the user starts dragging the map.
Called when the user stops dragging the map.
Map State Change Handlers
Called when the map viewport bounds change.
Called when the map center changes.
Called when the map zoom level changes.
Called when the map heading changes.
Called when the map tilt changes.
Called when the map type changes.
Called when the map projection changes.
Lifecycle Event Handlers
onLoad
(map: google.maps.Map) => void | Promise<void>
Called when the map instance is loaded. Receives the map instance as a parameter.onLoad={(map) => {
console.log('Map loaded:', map)
// Store map instance, add custom controls, etc.
}}
onUnmount
(map: google.maps.Map) => void | Promise<void>
Called when the map instance is about to be unmounted. Receives the map instance as a parameter.onUnmount={(map) => {
console.log('Map unmounting:', map)
// Cleanup, remove listeners, etc.
}}
Called when the map becomes idle after panning or zooming.
Called when the map div changes size.
Called when the map tiles have finished loading.
Usage Example
import { GoogleMap, LoadScript } from '@react-google-maps/api'
const containerStyle = {
width: '100%',
height: '400px'
}
const center = {
lat: 40.7128,
lng: -74.0060
}
function MapComponent() {
const [map, setMap] = useState<google.maps.Map | null>(null)
const onLoad = useCallback((map: google.maps.Map) => {
// Store map instance
setMap(map)
// Optional: Fit bounds, add controls, etc.
const bounds = new google.maps.LatLngBounds(center)
map.fitBounds(bounds)
}, [])
const onUnmount = useCallback(() => {
setMap(null)
}, [])
const onClick = useCallback((e: google.maps.MapMouseEvent) => {
console.log('Clicked at:', e.latLng?.toJSON())
}, [])
return (
<LoadScript googleMapsApiKey="YOUR_API_KEY">
<GoogleMap
mapContainerStyle={containerStyle}
center={center}
zoom={10}
onLoad={onLoad}
onUnmount={onUnmount}
onClick={onClick}
options={{
streetViewControl: false,
mapTypeControl: true,
}}
>
{/* Add child components like Markers, Polylines, etc. */}
</GoogleMap>
</LoadScript>
)
}
Advanced Usage
Custom Map Options
<GoogleMap
center={center}
zoom={10}
options={{
disableDefaultUI: true,
zoomControl: true,
mapTypeControl: false,
scaleControl: true,
streetViewControl: false,
rotateControl: false,
fullscreenControl: true,
styles: [
{
featureType: 'water',
elementType: 'geometry',
stylers: [{ color: '#193341' }]
}
]
}}
/>
Accessing Map Instance
const mapRef = useRef<google.maps.Map | null>(null)
const handleLoad = (map: google.maps.Map) => {
mapRef.current = map
}
const panToLocation = (lat: number, lng: number) => {
if (mapRef.current) {
mapRef.current.panTo({ lat, lng })
}
}
Notes
- The
GoogleMap component must be wrapped in a LoadScript or used with useLoadScript hook
- Child components have access to the map instance through React Context
- The map container requires explicit dimensions (width and height)
- Event handlers are automatically cleaned up on unmount
- The component is memoized for performance optimization
See Also
