React Components for the Google Maps JavaScript API

This is a TypeScript / JavaScript library to integrate the Maps JavaScript API into your React application. It comes with a collection of React components to create maps, markers, infowindows, geometry overlays (circles, polylines, polygons), and photorealistic [3D maps][gmp-maps-3d], as well as a set of hooks to use some of the Maps JavaScript API [Services][gmp-services] and [Libraries][gmp-libraries].

Installation

This library is available on npm as [@vis.gl/react-google-maps][npm-package].

npm install @vis.gl/react-google-maps

or

yarn add @vis.gl/react-google-maps

(PowerShell users: since @ has a special meaning in PowerShell, the package name has to be quoted)

Usage

Import the [APIProvider][api-provider] and wrap it around all components that should have access to the Maps JavaScript API. Any component within the context of the APIProvider can use the hooks and components provided by this library.

To render a simple map, add a [Map][api-map] component inside the APIProvider. Within the Map component, you can then add further components like [Marker][api-marker], [AdvancedMarker][api-adv-marker], [InfoWindow][api-infowindow], or geometry components such as [Circle][api-circle], [Polyline][api-polyline], and [Polygon][api-polygon] to render content on the map. For photorealistic 3D maps, use the [Map3D][api-map-3d] component instead.

For more advanced use-cases you can even add your own components to the map that make use of google.maps.OverlayView or google.maps.WebGlOverlayView.

import {AdvancedMarker, APIProvider, Map} from '@vis.gl/react-google-maps';

function App() {
  const position = {lat: 53.54992, lng: 10.00678};

  return (
    <APIProvider apiKey={'YOUR API KEY HERE'}>
      <Map defaultCenter={position} defaultZoom={10} mapId="DEMO_MAP_ID">
        <AdvancedMarker position={position} />
      </Map>
    </APIProvider>
  );
}

export default App;

Please see our [documentation][docs] or [examples][] for more in-depth information about this library.

Available Components

Component	Description
<APIProvider>	Loads the Google Maps JavaScript API and provides context.
<Map>	Renders a Google Map container and manages the map instance.
<MapControl>	Renders custom React components in one of the map's control containers.
<InfoWindow>	Displays a standard Google Maps Info Window overlay.
<Marker>	Displays a legacy Google Maps marker on the map.
<AdvancedMarker>	Renders a highly customizable modern Advanced Marker.
<Pin>	Customizes the background, border, and glyph colors of an AdvancedMarker.
<Circle>	Draws a circle at a given center and radius on the map.
<Rectangle>	Draws a rectangular vector boundary on the map.

Using other libraries of the Maps JavaScript API

Besides rendering maps, the Maps JavaScript API has a lot of [additional libraries][gmp-libraries] for things like geocoding, routing, the Places API, Street View, and a lot more.

These libraries are not loaded by default, which is why this module provides the [useMapsLibrary()][api-use-lib] hook to handle dynamic loading of additional libraries.

For example, if you just want to use the google.maps.geocoding.Geocoder class in a component and you don't even need a map, it can be implemented like this:

import {useMapsLibrary} from '@vis.gl/react-google-maps';

const MyComponent = () => {
  // useMapsLibrary loads the geocoding library, it might initially return `null`
  // if the library hasn't been loaded. Once loaded, it will return the library
  // object as it would be returned by `await google.maps.importLibrary()`
  const geocodingLib = useMapsLibrary('geocoding');
  const geocoder = useMemo(
    () => geocodingLib && new geocodingLib.Geocoder(),
    [geocodingLib]
  );

  useEffect(() => {
    if (!geocoder) return;

    // now you can use `geocoder.geocode(...)` here
  }, [geocoder]);

  return <></>;
};

const App = () => {
  return (
    <APIProvider apiKey={'YOUR API KEY HERE'}>
      <MyComponent />
    </APIProvider>
  );
};

Using Custom Elements of the Maps JavaScript API

The maps JavaScript API also provides a lot of custom elements like the [Places UI Kit][gmp-places-ui-kit] or the [Maps 3D][gmp-maps-3d] elements. This library provides the types needed to use these custom elements in a TypeScript / React application.

import {useMapsLibrary} from '@vis.gl/react-google-maps';

const My3DMap = (props: My3DMapProps) => {
  useMapsLibrary('maps3d');

  const {center, heading, tilt, range, roll} = props;

  return (
    <>
      <gmp-map-3d
        center={center}
        range={range}
        heading={heading}
        tilt={tilt}
        roll={roll}
        mode="SATELLITE"></gmp-map-3d>
    </>
  );
};

Available Custom Elements

Custom Element	Description
<gmp-map>	The native, web-component-based core 2D vector or raster map element.
<gmp-map-3d>	The foundational web component initializing Google's photorealistic 3D globe view.
<gmp-flattener>	Flattens a designated region of the 3D terrain mesh for clean placement of shapes or markers.
<gmp-popover>	An info-window style popup interface container optimized for positioning inside 3D viewports.
<gmp-advanced-marker>	A highly performance-optimized 2D map marker backing custom HTML, asset styling, and pin configurations.
<gmp-marker>	A standard billboard/sprite point asset mapped specifically within a 3D globe environment.
<gmp-marker-interactive>	An interactive variation of the standard 3D map marker designed to handle user click events and trigger popovers.
<gmp-marker-3d>	A volumetric, structural 3D point graphic supporting model scaling, extrusion, and altitude configurations.