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, as well as a set of hooks to use some of the Maps JavaScript API Services and Libraries.

Installation

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

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 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 component inside the APIProvider. Within the Map component, you can then add further components like Marker, AdvancedMarker, InfoWindow, or geometry components such as Circle, Polyline, and Polygon to render content on the map. For photorealistic 3D maps, use the Map3D 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 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.
<Polyline>	Draws a linear path on the map.
<Polygon>	Draws a closed polygon boundary on the map.
<StaticMap>	Renders a lightweight Google Static Maps API image.
<Map3D>	Renders a Next-Generation Photorealistic 3D Google Map.
<Marker3D>	Places a 3D object or icon within a Map3D view.
<Popover>	Renders an overlay/popup relative to a 3D element or coordinates.

Using other libraries of the Maps JavaScript API

Besides rendering maps, the Maps JavaScript API has a lot of additional 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() 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 or the 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.
<gmp-marker-3d-interactive>	An interactive version of the 3D volumetric point graphic that responds to pointer inputs.
<gmp-model-3d>	Renders and animates photorealistic native 3D mesh assets (such as glTF models) directly onto map coordinates.
<gmp-model-3d-interactive>	An interactive version of the native 3D mesh wrapper enabling pointer events directly on the object surface.
<gmp-polyline-3d>	Draws continuous multi-segment line paths across 3D spaces, complete with altitude properties and occlusion toggles.
<gmp-polyline-3d-interactive>	An interactive line-string path that listens for clicks and user interactions within the 3D view.
<gmp-polygon-3d>	Defines multi-coordinate geometric shapes and boundaries supporting geometric fills and extrusion on the 3D globe.
<gmp-polygon-3d-interactive>	An interactive geometric area overlay allowing users to trigger events by interacting with the 3D polygon.
<gmp-circle-path>	Generates and draws procedural circular spline layout paths mapped cleanly within 3D environments.
<gmp-route-3d>	Overlays and visualizes complex directional pathways, multi-modal steps, and routing telemetry on 3D viewports.
<gmp-air-quality-meter>	An environmental monitoring panel displaying localized real-time air safety indices and language-localized parameters.
<gmp-place-autocomplete>	A rich UI text input component packing fully automated address lookups and drop-down prediction items.
<gmp-basic-place-autocomplete>	A streamlined, lightweight variant of the predictive place autocomplete input widget.
<gmp-place-search>	A dynamic local directory UI component that outputs and arranges keyword and vicinity query listings.
<gmp-place-details>	A dense, modular location profile card showing media, business stats, scheduling charts, and contact datasets. Layout block styling and structure can be fine-tuned internally using individual child components.
<gmp-place-details-compact>	A responsive, space-conscious version of the comprehensive details card tailored for mobile viewports and tooltips.
<gmp-place-details-place-request>	An API context bridge element used inside a details panel to tie lookups to an explicit programmatic Google Place ID.
<gmp-place-details-location-request>	An API context bridge element used inside a details panel to tie lookups to explicit latitude/longitude coordinates.
<gmp-place-contextual>	Handles the presentation of embedded context layers and metadata driven by localized contextual token validation.
<gmp-place-contextual-list-config>	Exposes layout configuration rules to change styling distributions and list configurations of local context sheets.
<gmp-place-nearby-search-request>	A declarative widget component used to trigger and configure vicinity-focused radial place queries.
<gmp-place-text-search-request>	A declarative widget component used to structure and trigger string/text-based global search parameters.

Examples

Explore our examples directory on GitHub or the examples on our website for full implementation examples.

Supported Browsers

Being a library built around the Google Maps JavaScript API, we follow the same browser-support policy as the Google Maps Team, available here. Generally, the last two versions of the major browsers are officially supported.

It is not unlikely that browsers even far outside the given range will still work. We try our best to support as many browsers and versions as reasonably possible, but we won't actively investigate issues related to outdated browser versions.

However, if you can suggest small changes that could be made to even increase that range, we will be happy to include them, as long as they don't negatively affect the supported browsers.

Terms of Service

@vis.gl/react-google-maps uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform Terms of Service.

This library is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (e.g., Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to this library.

European Economic Area (EEA) developers

If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region. Learn more.

Help and Support

This library is offered via an open source license. It is not governed by the Google Maps Platform Technical Support Services Guidelines, the SLA, or the Deprecation Policy (however, any Google Maps Platform services used by this library remain subject to the Google Maps Platform Terms of Service).

If you find a bug or have a feature request, please file an issue on GitHub. If you would like to get answers to technical questions from other Google Maps Platform developers, feel free to open a thread in the discussions section on GitHub or ask a question through one of our developer community channels.

If you'd like to contribute, please check the Contributing guide.

You can also discuss this library on our Discord server.