React Google Maps

React component and hooks library for Google Maps

MapsReact
visgl/react-google-mapsvisgl.github.io/react-google-maps/@vis.gl/react-google-maps

README

[!IMPORTANT]

This project is still in it's alpha phase.

When using it be aware that things may not yet work as expected and can

break at any point. Releases happen often, so when you experience problems,

make sure you are using the latest version (check with npm outdated in

your project) before opening an issue.

We are still in a phase where we can easily make bigger changes, so we ask

you to please provide feedback

on everything you notice - including, but not limited to

- developer experience (installation, typings, sourcemaps, framework integration, ...)

- hard to understand concepts and APIs

- wrong, missing, outdated or inaccurate documentation

- use-cases not covered by the API

- missing features

- and of course any bugs you encounter

Also, feel free to use GitHub discussions to ask questions or start a new

discussion.


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 and
infowindows, and 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.

  1. ```sh
  2. npm install @vis.gl/react-google-maps
  3. ```

Usage


Import the APIProvider and wrap it around all components that should have
access to the Google Maps 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, or
InfoWindow to render content on the map.

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.

  1. ```tsx
  2. import {APIProvider, Map, Marker} from '@vis.gl/react-google-maps';

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

  7.   return (
  8.     <APIProvider apiKey={'YOUR API KEY HERE'}>
  9.       <Map center={position} zoom={10}>
  10.         <Marker position={position} />
  11.       </Map>
  12.     </APIProvider>
  13.   );
  14. }

  16. export default App;
  17. ```

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

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 want to use the google.maps.places.PlacesService class in
your component, you can implement it like this:

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

  4. const MyComponent = () => {
  5.   // triggers loading the places library and returns true once complete (the
  6.   // component calling the hook gets automatically re-rendered when this is
  7.   // the case)
  8.   const placesLib = useMapsLibrary('places');
  9.   const [placesService, setPlacesService] = useState(null);

  11.   useEffect(() => {
  12.     if (!placesLib) return;

  14.     setPlacesService(new placesLib.PlacesService());
  15.   }, [placesLib]);

  17.   useEffect(() => {
  18.     if (!placesService) return;

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

  23.   return <></>;
  24. };
  25. ```