Interacting with the Google Maps JavaScript API

With the provided components, you are able to declaratively create a Google map or a map with markers for example.

Besides that, there are three main ways and concepts to interact with the Maps JavaScript API on lower level with this library. You can use the provided hooks, the refs that are available for some components or use the useMapsLibrary hook to tap into other libraries and services of the Maps JavaScript API or craft your own custom hooks.

Hooks

There are several hooks that provide additional functionality for the map or maps you create. The main one being the useMap hook. This hooks give you access to the underlying google.maps.Map instance. Every child component wrapped in the <APIProvider>...</APIProvider> component has access to the map instance via this hook.

import React, {useEffect} from 'react';
import {APIProvider, useMap} from '@vis.gl/react-google-maps';

const MyComponent = () => {
  const map = useMap();

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

    // here you can interact with the imperative maps API
  }, [map]);

  return <></>;
};

const App = () => (
  <APIProvider apiKey={'YOUR API KEY HERE'}>
    <Map /* ... */></Map>

    <MyComponent />
  </APIProvider>
);

The useMapsLibrary hook can be utilized to load other parts of the Maps JavaScript API that are not loaded by default. For example, the Places Service or the Geocoding Service. Learn how to use this hook.

Refs

The <Marker> and the <AdvancedMarker> components accept a ref prop which provides access to the underlying google.maps.Marker / google.maps.marker.AdvancedMarkerElement instance.

Here is an example of how to use the useMarkerRef hook to get access to a marker instance. The same concept applies for the <AdvancedMarker> (using the useAdvancedMarkerRef hook).

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

const App = () => {
  const [markerRef, marker] = useMarkerRef();

  useEffect(() => {
    if (!marker) {
      return;
    }

    // do something with marker instance here
  }, [marker]);

  return (
    <APIProvider apiKey={'Your API key here'}>
      <Map zoom={12} center={{lat: 53.54992, lng: 10.00678}}>
        <Marker ref={markerRef} position={{lat: 53.54992, lng: 10.00678}} />
      </Map>
    </APIProvider>
  );
};

export default App;

Other Maps JavaScript API libraries and services

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 a hook useMapsLibrary() to handle dynamic loading of those libraries.

For example, if you want to write a component that needs to use the google.maps.places.PlacesService class, you can implement it like this:

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

const MyComponent = () => {
  const map = useMap();

  // triggers loading the places library and returns the API Object once complete (the
  // component calling the hook gets automatically re-rendered when this is
  // the case)
  const placesLibrary = useMapsLibrary('places');

  const [placesService, setPlacesService] = useState(null);

  useEffect(() => {
    if (!placesLibrary || !map) return;

    // when placesLibrary is loaded, the library can be accessed via the
    // placesLibrary API object
    setPlacesService(new placesLibrary.PlacesService(map));
  }, [placesLibrary, map]);

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

    // ...use placesService...
  }, [placesService]);

  return <></>;
};

Or you can extract your own hook from this:

function usePlacesService() {
  const map = useMap();
  const placesLibrary = useMapsLibrary('places');
  const [placesService, setPlacesService] = useState(null);

  useEffect(() => {
    if (!placesLibrary || !map) return;

    setPlacesService(new placesLibrary.PlacesService(map));
  }, [placesLibrary, map]);

  return placesService;
}

const MyComponent = () => {
  const placesService = usePlacesService();

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

    // ... use placesService ...
  }, [placesService]);

  return <></>;
};