Google Maps React Hooks

Description

This is a JavaScript library to easily implement a Google Maps map into your React application. It comes with a collection of React hooks to access the Google Maps map instance all over your components and to use some of the Google Maps Services or Libraries.

Table of contents

• Requirements
• Installation
• Library
• Basic Google Map Setup
• Hooks
  • Hooks Overview
  • Hooks Example Setup
• Examples
  • Examples Overview
• Development
  • Contribution
  • Quick Start

Requirements

You need to have React 16.8.0 or later installed to use the Hooks API.

Installation

npm install @ubilabs/google-maps-react-hooks -D

NOTE FOR WINDOWS USERS: We are using cross-env for environment variables to work on all platforms. There is an issue that npm uses cmd by default. The workaround is to add script-shell to powershell in your .npmrc. Please follow this setup to make it work.

Library

The full Google Maps React Hooks library can be found in the library directory.

Basic Google Map Setup

Import the GoogleMapsProvider and wrap it around your components. Make sure all components that should have access to the Google Maps map instance are nested inside the GoogleMapsProvider.

If you still can't see a map on your page, make sure that your map container has a height CSS property (by default it usually has no height) and that a center and zoom was set for your map.

import React, {useState, useCallback, forwardRef} from 'react';
import {GoogleMapsProvider} from '@ubilabs/google-maps-react-hooks';

function App() {
  const [mapContainer, setMapContainer] = useState(null);
  const mapRef = useCallback(node => {
    node && setMapContainer(node);
  }, []);

  const mapOptions = {
    // Add your map options here
    // `center` and `zoom` are required for every map to be displayed
    center: {lat: 53.5582447, lng: 9.647645},
    zoom: 6
  };

  return (
    <GoogleMapsProvider
      googleMapsAPIKey="YOUR API KEY HERE"
      mapContainer={mapContainer}
      mapOptions={mapOptions}>
      <React.StrictMode>
        <div ref={ref} style={{height: '100%'}} />
      </React.StrictMode>
    </GoogleMapsProvider>
  );
}

export default App;

The GoogleMapsProvider makes the Google Maps map instance available to any nested components with the useGoogleMap hook.

import React from 'react';
import {useGoogleMap} from '@ubilabs/google-maps-react-hooks';

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

  // Do something with the Google Maps map instance

  return (...);
};

Hooks

All hooks can be found here. Please checkout the documentation for each hook and have a look at the examples directory to see how each hook can be implemented.

Hooks Overview

• useGoogleMap
• useDirectionsService
• useDistanceMatrixService
• useElevationService
• useGeocodingService
• useMaxZoomService
• usePlacesService
• useAutocomplete
• useAutocompleteService

Hooks Example Setup

useGeocodingService

import React from 'react';
import {useGeocodingService} from '@ubilabs/google-maps-react-hooks';

const MyComponent = () => {
  const geocoder = useGeocodingService();

  // Do something with the geocoder

  return (...);
};

useAutocomplete

import React, {useRef, useState} from 'react';
import {useAutocomplete} from '@ubilabs/google-maps-react-hooks';

const MyComponent = () => {
  const inputRef = useRef(null);
  const [inputValue, setInputValue] = useState('');

  const onPlaceChanged = place => {
    if (place) {
      setInputValue(place.formatted_address || place.name);
    }

    // Keep focus on input element
    inputRef.current && inputRef.current.focus();
  };

  useAutocomplete({
    inputField: inputRef && inputRef.current,
    onPlaceChanged
  });

  const handleInputChange = event => {
    setInputValue(event.target.value);
  };

  return (
    <input ref={inputRef} value={inputValue} onChange={handleInputChange} />
  );
};

Examples

Explore our examples directory on GitHub for full implementation examples.

Examples Overview

• Basic Google Map
• Google Map with Markers
• Multiple Google Maps
• Directions Service
• Distance Matrix Service
• Elevation Service
• Geocoding Service
• Maximum Zoom Imagery Service
• Places Autocomplete Service
• Places Autocomplete Widget
• Places Service
• Places Service With Element
• Street View Panorama Map
• Street View Panorama With Element

Development (only for Maintainers)

Contribution

We are happy about your contribution. Please checkout the following guide to get started: Contribution Guide.

Also, make sure to follow our Coding Conventions when making commits.

Quick Start

Clone the repository and run

npm install

in the project root to install all dependencies.

To develop the Google Maps React Hooks library, start the project locally with

npm run start:library