The GroundOverlay component displays an image overlay on the map, anchored to specific geographic bounds.
Import
import { GroundOverlay } from '@react-google-maps/api';
Usage
import { GoogleMap, GroundOverlay } from '@react-google-maps/api';
function MapWithGroundOverlay() {
const bounds = {
north: 40.7628,
south: 40.7428,
east: -73.9528,
west: -73.9828,
};
return (
<GoogleMap
center={{ lat: 40.7528, lng: -73.9678 }}
zoom={13}
>
<GroundOverlay
url="https://example.com/overlay-image.png"
bounds={bounds}
opacity={0.8}
/>
</GoogleMap>
);
}
Props
The URL of the image to display as the overlay.
bounds
google.maps.LatLngBoundsLiteral
required
The bounds within which to display the image. Must include north, south, east, and west properties.
The opacity of the overlay, expressed as a number between 0 and 1. Default is 1.
Whether the overlay is visible. When set to false, the overlay is hidden by setting opacity to 0.
options
google.maps.GroundOverlayOptions
Additional options for configuring the ground overlay.
onClick
(e: google.maps.MapMouseEvent) => void
Callback fired when the overlay is clicked.Parameters:
e: The mouse event containing information about the click
onDblClick
(e: google.maps.MapMouseEvent) => void
Callback fired when the overlay is double-clicked.Parameters:
e: The mouse event containing information about the double-click
onLoad
(groundOverlay: google.maps.GroundOverlay) => void
Callback invoked when the ground overlay instance has loaded.Parameters:
groundOverlay: The ground overlay instance
onUnmount
(groundOverlay: google.maps.GroundOverlay) => void
Callback invoked when the component unmounts.Parameters:
groundOverlay: The ground overlay instance
Example with Click Handler
function InteractiveGroundOverlay() {
const handleClick = (e: google.maps.MapMouseEvent) => {
console.log('Overlay clicked at:', e.latLng?.toJSON());
};
return (
<GroundOverlay
url="https://example.com/overlay.png"
bounds={{
north: 40.7628,
south: 40.7428,
east: -73.9528,
west: -73.9828,
}}
onClick={handleClick}
opacity={0.7}
/>
);
}
TypeScript
import type { GroundOverlayProps } from '@react-google-maps/api';
const overlayProps: GroundOverlayProps = {
url: 'https://example.com/image.png',
bounds: {
north: 40.7628,
south: 40.7428,
east: -73.9528,
west: -73.9828,
},
opacity: 0.8,
visible: true,
};
