# visgl/react-google-maps for React map interfaces

> visgl/react-google-maps wraps the Google Maps JavaScript API in React components and hooks. It is a practical choice for React and TypeScript applications that need declarative map overlays, dynamic Maps libraries, or Maps 3D elements.

**visgl/react-google-maps** — React components and hooks for the Google Maps JavaScript API

- Repository: https://github.com/visgl/react-google-maps
- Website: https://visgl.github.io/react-google-maps/
- Stars: 1,949 · Forks: 193
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/visgl-react-google-maps

## Why APIProvider belongs at the React map boundary

visgl/react-google-maps addresses the impedance mismatch between React's component model and an imperative browser API. The Google Maps JavaScript API exposes objects such as maps, markers, geometry overlays, and service classes. The library places those objects behind React components and hooks, allowing application code to describe map contents in JSX instead of concentrating lifecycle and instance management in a large imperative initialization routine.

The central abstraction is APIProvider. It loads the Google Maps JavaScript API and provides its context to descendants. Components rendered below it can then access the library's map components and hooks. This boundary matters for an application with several isolated interface areas, because every map-related descendant expects the provider context.

The package targets applications built with React and TypeScript or JavaScript. Its component set covers the main rendering layer, including Map, Marker, AdvancedMarker, InfoWindow, Circle, Rectangle, Polyline, Polygon, MapControl, StaticMap, Map3D, and Marker3D. It also exposes useMapsLibrary for optional Maps JavaScript API libraries such as geocoding, routing, Places, and Street View. That makes it broader than a marker wrapper, although the project still remains tied to Google Maps rather than replacing the underlying API.

## How React components map to Google Maps objects

The visible data flow starts with APIProvider, which owns API loading and context. Map creates the map container and manages the underlying map instance. Child components then express locations and overlays. AdvancedMarker receives a position, while geometry components receive the coordinates and dimensions appropriate to circles, lines, polygons, and rectangles.

This arrangement keeps JavaScriptX focused on map content. A component can appear conditionally, receive ordinary React props, and participate in the application's state model. The library's role is to translate that declarative structure into Google Maps objects and their lifecycle.

Advanced usage is not restricted to the supplied components. The README says applications can add custom components based on google.maps.OverlayView or google.maps.WebGlOverlayView. This creates an extension point for behavior that does not correspond directly to a bundled component. It also means the library does not insulate an application from every Maps JavaScript API change. Custom map integrations still use Google's object model.

The package publishes separate entry points for the main package, server functionality, and 3D functionality. Its main metadata points to UMD and modern module builds under dist, with TypeScript declarations supplied through dist/index.d.ts. Consumers therefore receive both component typings and compiled JavaScript distributions rather than having to work from the repository source.

## Installing @vis.gl/react-google-maps and rendering a marker

Install the package with the package manager used by the React application. The README lists both npm and Yarn:

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

The corresponding Yarn command is documented as follows:

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

PowerShell users are warned in the README to quote the package name because `@` has special meaning in PowerShell. After installation, configure an API key for the Google Maps JavaScript API and wrap the map interface in APIProvider. The documented first-use structure places Map inside APIProvider and an AdvancedMarker inside Map:

```tsx
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;
```

This example establishes the required component hierarchy and supplies a center, zoom, map identifier, and marker position. It does not create the API key or map identifier. Those are external Google Maps configuration values that the application must already possess.

## Loading geocoding with useMapsLibrary

Maps JavaScript API libraries are not loaded by default. That choice avoids paying the loading cost for features an application never requests, but it introduces an asynchronous state that React code must handle. useMapsLibrary('geocoding') can initially return null. Once loading finishes, it returns the library object corresponding to the result of google.maps.importLibrary().

The documented pattern constructs a Geocoder only after the library becomes available. A memoized value depends on geocodingLib, and an effect returns early when geocoder is null. This prevents application code from attempting to instantiate a service before its constructor is available.

The limitation is visible in the shape of the example itself: consumers cannot treat the first hook result as an immediately usable API object. UI code must tolerate an unloaded state, disable actions, defer work, or otherwise avoid dereferencing null. The package handles loading, but it does not turn every asynchronous Maps service into a synchronous React value.

This mechanism also creates a practical difference between map rendering and service use. A component can call useMapsLibrary('geocoding') without rendering Map at all, as long as it remains inside APIProvider. The geocoder is created from the loaded library object, after which its geocode method can be used. That supports service-oriented React components without forcing a map canvas into the interface.

## Map3D, custom elements, and TypeScript boundaries

Map3D targets the photorealistic 3D Google Maps experience, while Marker3D and Popover handle content related to that view. The README also documents Maps 3D custom elements such as gmp-map-3d. JSX can set properties including center, range, heading, tilt, roll, and mode directly on the element. The example calls useMapsLibrary('maps3d') before rendering gmp-map-3d, which signals that the custom element's library still participates in dynamic loading.

This is useful for applications already using Google Maps 3D primitives, but it also exposes a boundary in the abstraction. The library supplies types for custom elements and React integration; the rendered object still belongs to the Google Maps JavaScript API. Attributes and element behavior remain tied to Google's API contract.

The package also names a separate ./3d export and types available under the custom element section of the README. Consumers who isolate 3D code into a separate bundle can use that package entry instead of pulling all 3D exports through the main entry. The repository contains dedicated examples for 3D maps, 3D markers, routes, route widgets, and popovers, which gives developers concrete starting points for those integrations.

StaticMap is a separate choice within the same package. The README describes it as a lightweight Static Maps API image rather than an interactive Map component. It can fit server-rendered or simple image-oriented use cases, but it should not be mistaken for the component and hook model used by the interactive API.

## Direct API integration as the genuine alternative

The clearest alternative is direct use of the Google Maps JavaScript API in a React component. Instead of APIProvider and Map, application code would create and update the Google map itself, manage event listeners, and remove them during teardown. Markers, overlays, and services would remain imperative objects. This approach can be appropriate for a codebase that has an existing integration layer or wants no wrapper dependency.

The difference is architectural rather than visual. visgl/react-google-maps distributes object ownership across a provider, a map component, and declarative children. Direct integration keeps more lifecycle code in application components. The wrapper is more convenient when a React team wants map contents to follow normal component composition, but it adds a library layer between React and Google's API.

Custom overlays also demonstrate why this is not an all-or-nothing decision. The README explicitly supports components using google.maps.OverlayView and google.maps.WebGlOverlayView. Such code necessarily retains knowledge of the underlying Google Maps API even when installed through the wrapper. Projects should compare their custom overlay requirements, server-rendering needs, bundle constraints, and familiarity with the raw API before choosing the extra abstraction.

## MIT licensing and the 1.10.x upgrade path

The repository and package metadata identify the project under the MIT License. That designation defines the permissions and conditions published with the library, but this review does not interpret whether a particular application meets its obligations. Projects should review LICENSE.md with their own legal process.

The package version in package.json is 1.10.1. Published release records list v1.10.1 on 2026-09-21, v1.10.0 on 2026-09-05, and v1.9.0 on 2026-07-03. The repository is not archived, and its last push was on 2026-10-15. Those facts indicate recent code activity, but the README does not provide a documented migration policy for upgrading between minor versions.

Adoption also carries an external upgrade dependency. Google can change or extend the Maps JavaScript API, while this package mediates its loading and exposes typed wrappers. Consumers who use google.maps types directly, custom overlay classes, or custom elements need to verify compatibility when upgrading either side of that boundary. The MIT license does not remove that operational consideration.

## Conclusion

React teams that want declarative access to Google Maps should evaluate this library after checking their API key setup, map identifier requirements, and need for client-side rendering. Projects that need a dependency-free integration or only a static map image are better served by direct Google Maps JavaScript API integration or StaticMap. The deciding implementation detail is whether APIProvider, Map, and the dynamic useMapsLibrary loading model fit the application's React architecture.

## FAQ

### How do I install visgl/react-google-maps in a React application?

Install `@vis.gl/react-google-maps` with `npm install @vis.gl/react-google-maps` or `yarn add @vis.gl/react-google-maps`. The README specifically notes that PowerShell users should quote the package name.

### Which component loads the Google Maps JavaScript API for visgl/react-google-maps?

APIProvider loads the Google Maps JavaScript API and supplies context to components rendered below it. The map components and hooks are intended to be used within that provider boundary.

### Why does useMapsLibrary initially return null?

Additional Maps JavaScript API libraries load dynamically, so `useMapsLibrary()` can return `null` before the requested library is available. Once loaded, it returns the library object associated with `google.maps.importLibrary()`.

### Can visgl/react-google-maps render photorealistic 3D maps?

Yes. The README documents Map3D for photorealistic 3D maps, Marker3D for 3D objects or icons, and typed Maps 3D custom elements such as `gmp-map-3d`.

### Does visgl/react-google-maps provide components other than the interactive Map?

Yes. Its component list includes Marker, AdvancedMarker, InfoWindow, geometry overlays, MapControl, StaticMap, and 3D components. It also supports hooks for additional Maps JavaScript API libraries.

## Sources

- [License: MIT](https://github.com/visgl/react-google-maps/blob/main/LICENSE)
- [Project website](https://visgl.github.io/react-google-maps/)
- [README](https://github.com/visgl/react-google-maps/blob/main/README.md)
- [Releases](https://github.com/visgl/react-google-maps/releases)
- [visgl/react-google-maps on GitHub](https://github.com/visgl/react-google-maps)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/visgl-react-google-maps