The OverlayView component allows you to render custom React content on a map at a specific geographic position or within specific bounds.
Import
import { OverlayView } from '@react-google-maps/api';
Usage
import { GoogleMap, OverlayView, OVERLAY_MOUSE_TARGET } from '@react-google-maps/api';
function MapWithOverlay() {
return (
<GoogleMap
center={{ lat: 40.7128, lng: -74.0060 }}
zoom={12}
>
<OverlayView
position={{ lat: 40.7128, lng: -74.0060 }}
mapPaneName={OVERLAY_MOUSE_TARGET}
>
<div style={{ background: 'white', padding: '10px' }}>
Custom overlay content
</div>
</OverlayView>
</GoogleMap>
);
}
Props
The map pane in which to display the overlay. See Pane Constants below. The React content to render in the overlay.
position
google.maps.LatLng | google.maps.LatLngLiteral
The geographic position at which to anchor the overlay.
bounds
google.maps.LatLngBounds | google.maps.LatLngBoundsLiteral
The bounds within which to position the overlay. Alternative to position.
The z-index of the overlay.
getPixelPositionOffset
(offsetWidth: number, offsetHeight: number) => { x: number; y: number }
A function that returns the pixel offset for positioning the overlay relative to the anchor point.Parameters:
offsetWidth: The width of the overlay elementoffsetHeight: The height of the overlay element
Returns: An object with x and y pixel offsets onLoad
(overlayView: google.maps.OverlayView) => void
Callback invoked when the overlay has been mounted and is ready.
onUnmount
(overlayView: google.maps.OverlayView) => void
Callback invoked when the overlay is about to be unmounted.
Pane Constants
The library exports constants for the available map panes. Use these with the mapPaneName prop:
Pane for overlays that should float above all other map content. This pane is the topmost pane and appears above markers.
Pane containing the map’s tiles. This is the base layer.
Pane containing markers. This appears above the map tiles.
Pane containing polylines, polygons, ground overlays, and tile layer overlays.
Pane for elements that should receive DOM mouse events. This is the most commonly used pane for interactive overlays.
Example with Pixel Offset
function CenteredOverlay() {
const getPixelPositionOffset = (width: number, height: number) => ({
x: -(width / 2),
y: -(height / 2),
});
return (
<OverlayView
position={{ lat: 40.7128, lng: -74.0060 }}
mapPaneName={OVERLAY_MOUSE_TARGET}
getPixelPositionOffset={getPixelPositionOffset}
>
<div style={{ background: 'white', padding: '10px', borderRadius: '4px' }}>
Centered marker
</div>
</OverlayView>
);
}
TypeScript
import type { OverlayViewProps, PaneNames } from '@react-google-maps/api';
const overlayProps: OverlayViewProps = {
position: { lat: 40.7128, lng: -74.0060 },
mapPaneName: 'overlayMouseTarget',
children: <div>Custom content</div>,
};
