google-maps-js-api-react

This library use Suspense, so it requires React v18 or later.

This package provides a simple and efficient way to work with the Google Maps API, enabling map-based applications to be built with ease. With minimal setup, Google Maps functionality can be integrated into React applications using the components and hooks provided by this package. The package is designed to be fast, lightweight, and tree-shakeable, providing a performant solution for integrating Google Maps into React applications.

Installation

using npm:

npm i --save google-maps-js-api-react google-maps-js-api-loader && npm install --save-dev @types/google.maps

or yarn:

yarn add i google-maps-js-api-react google-maps-js-api-loader && yarn add -D @types/google.maps

or pnpm:

pnpm add i google-maps-js-api-react google-maps-js-api-loader && pnpm add -D @types/google.maps

---

Example

1import { GoogleMap, Marker, OverlayView } from 'google-maps-js-api-react';
2import { GoogleMapsLoader } from 'google-maps-js-api-loader';
3import { useCallback } from 'react';
4
5GoogleMapsLoader({ apiKey: API_KEY }, { defer: true });
6
7const Map = () => {
8  const handleClick = useCallback(() => console.log('clicked'), []);
9
10  return (
11    <GoogleMap
12      defaultOptions={{
13        center: { lat: -31.56391, lng: 147.154312 },
14        zoom: 6,
15      }}
16    >
17      <Marker
18        position={{ lat: -31.56391, lng: 147.154312 }}
19        onClick={handleClick}
20      />
21      <OverlayView
22        lat={-37.75}
23        lng={145.116667}
24        preventMapHits
25        render={(ref) => (
26          <div ref={ref} style={{ background: 'red' }} onClick={handleClick}>
27            dot
28          </div>
29        )}
30      />
31    </GoogleMap>
32  );
33};

All components (except OverlayView) is not designed to implement "controlled" React logic. For instance, consider the following example:

1const Map = () => {
2  const [zoom, setZoom] = useState(5);
3
4  return <GoogleMap zoom={zoom} />;
5};

Here, the zoom level of the map is not limited to 5 and can be modified by the user. However, if the value of the zoom variable is changed, the zoom level of the map will also be modified accordingly.

API

• Components
  • GoogleMap
  • OverlayView
  • Marker
  • Polygon
  • Polyline
  • Circle
  • Rectangle
  • DrawingManager
  • HeatmapLayer
• Hooks
  • useGoogleMap
  • usePane
  • useGoogleMapsLoad
  • useGoogleMapsCompletion
  • useGoogleMapsStatus
  • useMarkerCluster

Components

GoogleMap

Map implementation

It creates instance of Map only once and will reuse this instance whenever possible, avoiding unnecessary reinitialization

1type GoogleMapProps = {
2  onBoundsChanged?(
3    this: google.maps.Map,
4    bounds: google.maps.LatLngBounds
5  ): void;
6  onCenterChanged?(this: google.maps.Map, center: google.maps.LatLng): void;
7  onDrag?(this: google.maps.Map): void;
8  onDragEnd?(this: google.maps.Map): void;
9  onDragStart?(this: google.maps.Map): void;
10  onHeadingChanged?(this: google.maps.Map, heading: number): void;
11  onIdle?(this: google.maps.Map): void;
12  onMapTypeIdChanged?(this: google.maps.Map, mapTypeId: string): void;
13  onProjectionChanged?(
14    this: google.maps.Map,
15    projection: google.maps.Projection
16  ): void;
17  onResize?(this: google.maps.Map): void;
18  onTilesLoaded?(this: google.maps.Map): void;
19  onTiltChanged?(this: google.maps.Map, tilt: number): void;
20  onZoomChanged?(this: google.maps.Map, zoom: number): void;
21  onClick?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
22  onContextMenu?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
23  onDoubleClick?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
24  onMouseDown?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
25  onMouseUp?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
26  onMouseMove?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
27  onMouseOut?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
28  onMouseOver?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
29  onRightClick?(this: google.maps.Map, e: google.maps.MapMouseEvent): void;
30  center?: google.maps.LatLng | google.maps.LatLngLiteral;
31  clickableIcons?: boolean;
32  heading?: number;
33  mapTypeId?: string;
34  streetView?: google.maps.StreetViewPanorama;
35  zoom?: number;
36  defaultOptions?: google.maps.MapOptions;
37  className?: string;
38  style?: React.CSSProperties;
39  children?: React.ReactNode;
40  fallback?: React.ReactNode;
41  preventLoad?: boolean;
42};
43
44const GoogleMap: React.ForwardRefExoticComponent<
45  GoogleMapProps & React.RefAttributes<google.maps.Map>
46>;

---

OverlayView

1type OverlayViewProps = {
2  mapPaneLayer?: keyof google.maps.MapPanes;
3  preventMapHitsAndGestures?: boolean;
4  preventMapHits?: boolean;
5  lat: number;
6  lng: number;
7  render(ref: React.RefCallback<HTMLElement>): React.ReactElement;
8};
9
10const OverlayView: FC<OverlayViewProps>;

OverlayView implementation

Name	Description	Default
mapPaneLayer?	see link	'overlayMouseTarget'
preventMapHits?	stops click or tap on the element from bubbling up to the map. Use this to prevent the map from triggering "click" events	false
preventMapHitsAndGestures?	stops click, tap, drag, and wheel events on the element from bubbling up to the map. Use this to prevent map dragging and zooming, as well as map "click" events	false
render	render prop, a function that returns a React element and provides the ability to attach ref to it

1const SomeComponent = forwardRef(({ children }, ref) => (
2  <div ref={ref}>{children}</div>
3));
4
5const AnotherComponent = () => {
6  return (
7    <OverlayView
8      lat={0}
9      lng={0}
10      render={(ref) => <SomeComponent ref={ref}>hi</SomeComponent>}
11    />
12  );
13};

---

Marker

Marker implementation

1type MarkerProps = {
2  onAnimationChanged?(
3    this: google.maps.Marker,
4    animation: google.maps.Animation
5  ): void;
6  onClickableChanged?(this: google.maps.Marker, clickable: boolean): void;
7  onCursorChanged?(this: google.maps.Marker, cursor: string): void;
8  onDraggableChanged?(this: google.maps.Marker, draggable: boolean): void;
9  onFlatChanged?(this: google.maps.Marker): void;
10  onIconChanged?(
11    this: google.maps.Marker,
12    icon: string | google.maps.Icon | google.maps.Symbol
13  ): void;
14  onPositionChanged?(
15    this: google.maps.Marker,
16    position: google.maps.LatLng
17  ): void;
18  onShapeChanged?(
19    this: google.maps.Marker,
20    shape: google.maps.MarkerShape
21  ): void;
22  onTitleChanged?(this: google.maps.Marker, title: string): void;
23  onVisibleChanged?(this: google.maps.Marker, visible: boolean): void;
24  onZIndexChanged?(this: google.maps.Marker, zIndex: number): void;
25  onClick?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
26  onContextMenu?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
27  onDoubleClick?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
28  onDrag?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
29  onDragEnd?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
30  onDragStart?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
31  onMouseDown?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
32  onMouseMove?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
33  onMouseOut?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
34  onMouseOver?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
35  onMouseUp?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
36  onRightClick?(this: google.maps.Marker, e: google.maps.MapMouseEvent): void;
37  animation?: google.maps.Animation;
38  clickable?: boolean;
39  cursor?: string;
40  draggable?: boolean;
41  icon?: string | google.maps.Icon | google.maps.Symbol;
42  label?: string | google.maps.MarkerLabel;
43  opacity?: number;
44  position?: google.maps.LatLngLiteral | google.maps.LatLng;
45  shape?: google.maps.MarkerShape;
46  title?: string;
47  visible?: boolean;
48  zIndex?: number;
49  defaultOptions?: google.maps.MarkerOptions;
50};
51
52const Marker: React.ForwardRefExoticComponent<
53  MarkerProps & React.RefAttributes<google.maps.Marker>
54>;

---

Polygon

Polygon implementation

1type PolygonProps = {
2  onClick?(this: google.maps.Polygon, e: google.maps.PolyMouseEvent): void;
3  onContextMenu?(
4    this: google.maps.Polygon,
5    e: google.maps.PolyMouseEvent
6  ): void;
7  onDoubleClick?(
8    this: google.maps.Polygon,
9    e: google.maps.PolyMouseEvent
10  ): void;
11  onMouseDown?(this: google.maps.Polygon, e: google.maps.PolyMouseEvent): void;
12  onMouseMove?(this: google.maps.Polygon, e: google.maps.PolyMouseEvent): void;
13  onMouseOut?(this: google.maps.Polygon, e: google.maps.PolyMouseEvent): void;
14  onMouseOver?(this: google.maps.Polygon, e: google.maps.PolyMouseEvent): void;
15  onMouseUp?(this: google.maps.Polygon, e: google.maps.PolyMouseEvent): void;
16  onRightClick?(this: google.maps.Polygon, e: google.maps.PolyMouseEvent): void;
17  onDrag?(this: google.maps.Polygon, e: google.maps.MapMouseEvent): void;
18  onDragEnd?(this: google.maps.Polygon, e: google.maps.MapMouseEvent): void;
19  onDragStart?(this: google.maps.Polygon, e: google.maps.MapMouseEvent): void;
20  draggable?: boolean;
21  editable?: boolean;
22  paths?: any[] | google.maps.MVCArray<any>;
23  visible?: boolean;
24  defaultOptions?: google.maps.PolygonOptions;
25};
26
27const Polygon: React.ForwardRefExoticComponent<
28  PolygonProps & React.RefAttributes<google.maps.Polygon>
29>;

---

Polyline

Polyline implementation

1type PolylineProps = {
2  onClick?(this: google.maps.Polyline, e: google.maps.PolyMouseEvent): void;
3  onContextMenu?(
4    this: google.maps.Polyline,
5    e: google.maps.PolyMouseEvent
6  ): void;
7  onDoubleClick?(
8    this: google.maps.Polyline,
9    e: google.maps.PolyMouseEvent
10  ): void;
11  onMouseDown?(this: google.maps.Polyline, e: google.maps.PolyMouseEvent): void;
12  onMouseMove?(this: google.maps.Polyline, e: google.maps.PolyMouseEvent): void;
13  onMouseOut?(this: google.maps.Polyline, e: google.maps.PolyMouseEvent): void;
14  onMouseOver?(this: google.maps.Polyline, e: google.maps.PolyMouseEvent): void;
15  onMouseUp?(this: google.maps.Polyline, e: google.maps.PolyMouseEvent): void;
16  onRightClick?(
17    this: google.maps.Polyline,
18    e: google.maps.PolyMouseEvent
19  ): void;
20  onDrag?(this: google.maps.Polyline, e: google.maps.MapMouseEvent): void;
21  onDragEnd?(this: google.maps.Polyline, e: google.maps.MapMouseEvent): void;
22  onDragStart?(this: google.maps.Polyline, e: google.maps.MapMouseEvent): void;
23  draggable?: boolean;
24  editable?: boolean;
25  path?:
26    | google.maps.MVCArray<google.maps.LatLng>
27    | Array<google.maps.LatLngLiteral | google.maps.LatLng>;
28  visible?: boolean;
29  defaultOptions?: google.maps.PolylineOptions;
30};
31
32const Polyline: React.ForwardRefExoticComponent<
33  PolygonProps & React.RefAttributes<google.maps.Polyline>
34>;

---

Circle

Circle implementation

1type CircleProps = {
2  onCenterChanged?(this: google.maps.Circle, center: google.maps.LatLng): void;
3  onRadiusChanged?(this: google.maps.Circle, radius: number): void;
4  onClick?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
5  onContextMenu?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
6  onDoubleClick?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
7  onDrag?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
8  onDragEnd?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
9  onDragStart?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
10  onMouseDown?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
11  onMouseMove?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
12  onMouseOut?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
13  onMouseOver?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
14  onMouseUp?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
15  onRightClick?(this: google.maps.Circle, e: google.maps.MapMouseEvent): void;
16  center?: google.maps.LatLngLiteral | google.maps.LatLng;
17  draggable?: boolean;
18  editable?: boolean;
19  radius?: number;
20  visible?: boolean;
21  defaultOptions?: google.maps.CircleOptions;
22};
23
24const Circle: React.ForwardRefExoticComponent<
25  CircleProps & React.RefAttributes<google.maps.Circle>
26>;

---

Rectangle

Rectangle implementation

1type RectangleProps = {
2  onBoundsChanged?(
3    this: google.maps.Rectangle,
4    bounds: google.maps.LatLngBounds
5  ): void;
6  onClick?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
7  onContextMenu?(
8    this: google.maps.Rectangle,
9    e: google.maps.MapMouseEvent
10  ): void;
11  onDoubleClick?(
12    this: google.maps.Rectangle,
13    e: google.maps.MapMouseEvent
14  ): void;
15  onDrag?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
16  onDragEnd?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
17  onDragStart?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
18  onMouseDown?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
19  onMouseMove?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
20  onMouseOut?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
21  onMouseOver?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
22  onMouseUp?(this: google.maps.Rectangle, e: google.maps.MapMouseEvent): void;
23  onRightClick?(
24    this: google.maps.Rectangle,
25    e: google.maps.MapMouseEvent
26  ): void;
27  bounds?: google.maps.LatLngBounds | google.maps.LatLngBoundsLiteral;
28  draggable?: boolean;
29  editable?: boolean;
30  visible?: boolean;
31  defaultOptions?: google.maps.RectangleOptions;
32};
33
34const Rectangle: React.ForwardRefExoticComponent<
35  RectangleProps & React.RefAttributes<google.maps.Rectangle>
36>;

---

DrawingManager

DrawingManager implementation

1type DrawingManagerProps = {
2  onCircleComplete?(
3    this: google.maps.drawing.DrawingManager,
4    circle: google.maps.Circle
5  ): void;
6  onMarkerComplete?(
7    this: google.maps.drawing.DrawingManager,
8    marker: google.maps.Marker
9  ): void;
10  onOverlayComplete?(
11    this: google.maps.drawing.DrawingManager,
12    event: google.maps.drawing.OverlayCompleteEvent
13  ): void;
14  onPolygonComplete?(
15    this: google.maps.drawing.DrawingManager,
16    polygon: google.maps.Polygon
17  ): void;
18  onPolylineComplete?(
19    this: google.maps.drawing.DrawingManager,
20    polyline: google.maps.Polyline
21  ): void;
22  onRectangleComplete?(
23    this: google.maps.drawing.DrawingManager,
24    rectangle: google.maps.Rectangle
25  ): void;
26  drawingMode?: google.maps.drawing.OverlayType;
27  defaultOptions?: google.maps.drawing.DrawingManagerOptions;
28  preventLoad?: boolean;
29};
30
31const DrawingManager: React.ForwardRefExoticComponent<
32  DrawingManagerProps & React.RefAttributes<google.maps.drawing.DrawingManager>
33>;

HeatmapLayer

HeatmapLayer implementation

1type HeatmapLayerProps = {
2  data?:
3    | google.maps.MVCArray<
4        google.maps.LatLng | google.maps.visualization.WeightedLocation
5      >
6    | Array<google.maps.LatLng | google.maps.visualization.WeightedLocation>;
7  defaultOptions?: google.maps.visualization.HeatmapLayerOptions;
8  preventLoad?: boolean;
9};
10
11const HeatmapLayer: React.ForwardRefExoticComponent<
12  HeatmapLayerProps &
13    React.RefAttributes<google.maps.visualization.HeatmapLayer>
14>;

---

Hooks

useGoogleMap

1const useGoogleMap: () => google.maps.Map;

Context of GoogleMap component

---

usePane

1const usePane: (pane: keyof google.maps.MapPanes) => Element;

Hook to retrieve a specific pane from GoogleMap, useful to creating portals

1const ZoomButton = () => {
2  const map = useGoogleMap();
3
4  return createPortal(
5    usePane('overlayMouseTarget'),
6    <button
7      onClick={() => {
8        map.setZoom(7);
9      }}
10    >
11      zoom
12    </button>
13  );
14};
15
16const Map = () => (
17  <GoogleMap>
18    <ZoomButton />
19  </GoogleMap>
20);

---

useGoogleMapsLoad

1const useGoogleMapsLoad: {
2  (): void;
3  <L extends keyof GoogleMapsLibraries>(library: L): GoogleMapsLibraries[L];
4  <const A extends (keyof GoogleMapsLibraries)[]>(
5    ...libraries: A
6  ): {
7    [Index in keyof A]: GoogleMapsLibraries[A[Index]];
8  };
9};

Hook for loading google maps script or specific library/libraries

Works only for Suspense wrapped components

---

useGoogleMapsCompletion

1const useGoogleMapsCompletion: {
2  (): void;
3  <L extends GoogleMapsLibrary>(library: L): GoogleMapsLibraries[L];
4  <const A extends GoogleMapsLibrary[]>(
5    ...libraries: A
6  ): {
7    [Index in keyof A]: GoogleMapsLibraries[A[Index]];
8  };
9};

Hook for awaiting loading of google.maps script or specific library/libraries

Works only for Suspense wrapped components

---

useGoogleMapsStatus

1const useGoogleMapsStatus: (
2  library?: GoogleMapsLibrary
3) => 'none' | 'loading' | 'loaded' | 'error';

Hook for getting status of google.maps script or specific library

It not provokes loading of script/library

---

useMarkerCluster

This hook has been moved to use-marker-cluster library

---

License

MIT © Krombik