googlemaps-react-primitives

📍 Google Maps primitives for React

Rationale

When looking for a way to add Google Maps to a React application you'll find tons of different solutions and libraries.

The idea behind this module is to stick to Google's official guide for React as close as possible and provide the missing bits and pieces.

Features

• Written in TypeScript
• Super lightweight
• Tree shakeable
• Works with @googlemaps/react-wrapper

Installation

npm install @googlemaps/react-wrapper googlemaps-react-primitives
npm install -D @types/google.maps

Usage

This basic example shows everything that's needed in order to display a Google Map with its default options:

import { Wrapper, Status } from "@googlemaps/react-wrapper";
import { GoogleMap } from "googlemaps-react-primitives";

function renderLoadingStatus(status: Status) {
  return <h1>{status}</h1>;
}

function App() {
  return (
    <Wrapper apiKey="YOUR_API_KEY" render={renderLoadingStatus}>
      <GoogleMap style={{ width: "400px", height: "400px" }} />
    </Wrapper>
  );
}

To configure the map you can pass all supported options as props:

<GoogleMap center={{ lat: 53.551086, lng: 9.993682 }} zoom={11} />

Map Markers

You can place standard markers on the map using the Marker component. It supports all marker options as props.

import { GoogleMap, Marker } from "googlemaps-react-primitives";

function MyMap() {
  return (
    <GoogleMap>
      <Marker position={{ lat: 53.551086, lng: 9.993682 }} />
      <Marker position={{ lat: 52.520008, lng: 13.404954 }} />
    </GoogleMap>
  );
}

You can use this primitive to create a customized markers, for example to draw a custom path:

function MyMarker(props: google.maps.MarkerOptions) {
  return (
    <Marker
      {...props}
      icon={{
        path: "M9 22C9 22 18 16 18 9C18 4.02944 13.9706 0 9 0C4.02944 0 0 4.02944 0 9C0 16 9 22 9 22ZM12 9C12 10.6569 10.6569 12 9 12C7.34315 12 6 10.6569 6 9C6 7.34315 7.34315 6 9 6C10.6569 6 12 7.34315 12 9Z",
        strokeColor: "#FFFFFF",
        fillColor: "#009A9E",
        fillOpacity: 0.8,
        scale: 1.5,
        anchor: new google.maps.Point(9, 22),
      }}
    />
  );
}

By default, Google markers can only provide a single SVG path. To allow more complex icons, this library includes a utility component to render complete SVGs:

import { GoogleMap, SvgMarker } from "googlemaps-react-primitives";

function MyMap() {
  return (
    <GoogleMap>
      <SvgMarker
        position={{ lat: 48.864716, lng: 2.349014 }}
        svg={`<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
              <path fill="#e74c3c" d="M12 0a8 8 0 0 0-7 12l7 12 7-12a8 8 0 0 0-7-12zm0 4a4 4 0 1 1 0 8 4 4 0 0 1 0-8z" />
              <path fill="#c0392b" d="M12 3a5 5 0 1 0 0 10 5 5 0 0 0 0-10zm0 2a3 3 0 1 1 0 6 3 3 0 0 1 0-6z" />
            </svg>`}
      />
    </GoogleMap>
  );
}

Overlays

You can render arbitrary React component onto the map by using the Overlay component:

import { GoogleMap, Overlay } from "googlemaps-react-primitives";

function MyMap() {
  return (
    <GoogleMap>
      <Overlay position={{ lat: 123, lng: 456 }}>
        <div>Hello</div>
      </Overlay>
      <Overlay position={{ lat: 124, lng: 457 }}>
        <div>World</div>
      </Overlay>
    </GoogleMap>
  );
}

As with custom markers, it makes sense to create your own component that uses the Overlay primitive. Note that the overlay content is rendered into an absolutely positioned div and the top-left corner is placed at the given coordinates. You can use a CSS transform to center it horizontally:

interface Props {
  position: google.maps.LatLngLiteral;
  text: string;
}

function MyOverlay({ position, text }: Props) {
  return (
    <Overlay position={position} preventMapHits>
      <div style={{ transform: "translateX(-50%)" }}>{text}</div>
    </Overlay>
  );
}

Note: You can pass the preventMapHits property to stop clicks etc. from bubbling up to the map.

Polylines

You can draw lines on the map using the <Polyline> primitive:

import { GoogleMap, Polyline } from "googlemaps-react-primitives";

function MyMap() {
  return (
    <GoogleMap>
      <Polyline
        path={[
          { lat: 48.137154, lng: 11.576124 },
          { lat: 48.210033, lng: 16.363449 },
        ]}
        strokeColor="red"
      />
    </GoogleMap>
  );
}

Encoded Polylines

If you want to draw encoded polylines, you can use the <EncodedPolyline /> primitive.

NOTE: Decoding requires the geometry library to be loaded:

import { GoogleMap, EncodedPolyline } from "googlemaps-react-primitives";

function MyMap() {
  return (
    <GoogleMap libraries={["geometry"]}>
      <EncodedPolyline unescape location="ayp_I}cypAgkhElgyS" />
    </GoogleMap>
  );
}

NOTE: Polyline strings returned by the Google Directions API contain escaped backslashes. In order to use them directly you can pass the unescape prop.

Auto-fitting the map view

When placing markers or overlays on the map you can pass the autoFit prop in order to automatically center and zoom the map so that all nested markers and overlays are visible in the initial viewport.

import { GoogleMap, Marker } from "googlemaps-react-primitives";

function MyMap() {
  return (
    <GoogleMap autoFit maxZoom={14}>
      <Marker position={{ lat: 123, lng: 456 }} />
      <Marker position={{ lat: 124, lng: 457 }} />
    </GoogleMap>
  );
}

Accessing the map instance

When you write custom components that need to access the map instance, you can use the useMap() hook.

Viewing the example

When you check out the repository you can view the example using the following command:

VITE_API_KEY=<yourApiKey> npm start

License

MIT