The GoogleMapReact component is the main interface for integrating Google Maps with React applications. It provides comprehensive props for map configuration, event handling, and child component management.
The main React component that renders a Google Map and manages child components positioned by lat/lng coordinates.
/**
* Main GoogleMapReact component
* @param props - Configuration props for the map
* @returns React component rendering Google Map
*/
function GoogleMapReact(props: GoogleMapReactProps): JSX.Element;
interface GoogleMapReactProps {
// API Configuration (Required)
bootstrapURLKeys: BootstrapURLKeys;
// Position and Zoom Control
center?: LatLng;
defaultCenter?: LatLng;
zoom?: number;
defaultZoom?: number;
// Event Handlers
onClick?: ClickHandler;
onChange?: ChangeHandler;
onBoundsChange?: BoundsChangeHandler; // Deprecated but still available
onChildClick?: ChildEventHandler;
onChildMouseDown?: ChildEventHandler;
onChildMouseUp?: ChildEventHandler;
onChildMouseMove?: ChildEventHandler;
onChildMouseEnter?: ChildEventHandler;
onChildMouseLeave?: ChildEventHandler;
onZoomAnimationStart?: (zoomLevel: number) => void;
onZoomAnimationEnd?: (zoomLevel: number) => void;
onDrag?: (map: google.maps.Map) => void;
onDragEnd?: (map: google.maps.Map) => void;
onMapTypeIdChange?: (mapTypeId: string) => void;
onTilesLoaded?: () => void;
onGoogleApiLoaded?: GoogleApiHandler;
// Map Configuration
options?: MapOptions;
style?: React.CSSProperties;
draggable?: boolean;
resetBoundsOnResize?: boolean;
// Hover System
distanceToMouse?: DistanceFunction;
hoverDistance?: number;
debounced?: boolean;
margin?: [number, number, number, number];
// Advanced Features
layerTypes?: LayerType[];
heatmap?: HeatmapConfig;
heatmapLibrary?: boolean;
shouldUnregisterMapOnUnmount?: boolean;
overlayViewDivStyle?: { [key: string]: any };
experimental?: boolean;
yesIWantToUseGoogleMapApiInternals?: boolean;
// Deprecated
apiKey?: string;
googleMapLoader?: any;
// Child Components
children?: React.ReactNode;
}Configuration for Google Maps API loading and initialization.
interface BootstrapURLKeys {
key: string;
language?: string;
region?: string;
libraries?: string[];
[key: string]: any;
}Usage Example:
<GoogleMapReact
bootstrapURLKeys={{
key: "YOUR_API_KEY",
language: "en",
region: "US",
libraries: ["places", "geometry"]
}}
// ... other props
/>Props for controlling map position and zoom level.
type LatLng = [number, number] | { lat: number; lng: number };Usage Examples:
// Controlled map (props change updates map)
<GoogleMapReact
center={{ lat: 37.7749, lng: -122.4194 }}
zoom={10}
onChange={({ center, zoom }) => {
setCenter(center);
setZoom(zoom);
}}
/>
// Uncontrolled map (initial position only)
<GoogleMapReact
defaultCenter={[37.7749, -122.4194]}
defaultZoom={10}
/>Callback functions for map and child component interactions.
interface ClickHandler {
(args: {
x: number;
y: number;
lat: number;
lng: number;
event: MouseEvent;
}): void;
}
interface ChangeHandler {
(args: {
center: { lat: number; lng: number };
zoom: number;
bounds: any;
marginBounds?: any;
size: { width: number; height: number };
}): void;
}
interface BoundsChangeHandler {
(
center: [number, number] | { lat: number; lng: number },
zoom: number,
bounds: [number, number, number, number],
marginBounds: [number, number, number, number]
): void;
}
interface ChildEventHandler {
(childKey: any, childProps: any): void;
}
interface GoogleApiHandler {
(args: {
map: google.maps.Map;
maps: typeof google.maps;
ref: HTMLDivElement;
}): void;
}Usage Examples:
<GoogleMapReact
onClick={({ lat, lng, x, y }) => {
console.log('Map clicked at:', lat, lng);
console.log('Screen coordinates:', x, y);
}}
onChange={({ center, zoom, bounds }) => {
console.log('Map changed:', { center, zoom, bounds });
}}
onChildClick={(key, childProps) => {
console.log('Child clicked:', key, childProps);
}}
onGoogleApiLoaded={({ map, maps }) => {
// Access Google Maps API directly
const marker = new maps.Marker({
position: { lat: 37.7749, lng: -122.4194 },
map: map
});
}}
yesIWantToUseGoogleMapApiInternals
/>Configuration options for Google Maps appearance and behavior.
type MapOptions = object | ((maps: typeof google.maps) => object);Usage Examples:
// Static options
<GoogleMapReact
options={{
streetViewControl: false,
mapTypeControl: false,
styles: [
{
featureType: "poi",
elementType: "labels",
stylers: [{ visibility: "off" }]
}
]
}}
/>
// Dynamic options (function)
<GoogleMapReact
options={(maps) => ({
streetViewControl: false,
mapTypeControl: false,
gestureHandling: 'greedy',
styles: [
{
featureType: "poi",
elementType: "labels",
stylers: [{ visibility: "off" }]
}
]
})}
/>Configuration for the internal hover detection algorithm.
interface DistanceFunction {
(
pt: { x: number; y: number },
mousePos: { x: number; y: number },
markerProps: any
): number;
}Usage Example:
<GoogleMapReact
hoverDistance={40}
debounced={true}
distanceToMouse={(pt, mousePos) => {
// Custom distance calculation
return Math.sqrt(
Math.pow(pt.x - mousePos.x, 2) +
Math.pow(pt.y - mousePos.y, 2)
);
}}
/>CSS styling for the map container.
interface MapStyle extends React.CSSProperties {
width?: string | number;
height?: string | number;
}Usage Example:
<GoogleMapReact
style={{
width: '100%',
height: '400px',
position: 'relative'
}}
/>The GoogleMapReact component provides sensible defaults:
{
distanceToMouse: (pt, mousePos) => Math.sqrt((pt.x - mousePos.x) ** 2 + (pt.y - mousePos.y) ** 2),
hoverDistance: 30,
debounced: true,
options: {
overviewMapControl: false,
streetViewControl: false,
rotateControl: true,
mapTypeControl: false,
styles: [
{
featureType: 'poi',
elementType: 'labels',
stylers: [{ visibility: 'off' }]
}
],
minZoom: 3
},
style: {
width: '100%',
height: '100%',
margin: 0,
padding: 0,
position: 'relative'
},
layerTypes: [],
heatmap: {},
heatmapLibrary: false,
shouldUnregisterMapOnUnmount: true,
yesIWantToUseGoogleMapApiInternals: false,
resetBoundsOnResize: false
}