📍 Google Maps primitives for React
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.
- Written in TypeScript
- Super lightweight
- Tree shakeable
- Works with @googlemaps/react-wrapper
npm install @googlemaps/react-wrapper googlemaps-react-primitives
npm install -D @types/google.maps
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} />
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="https://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>
);
}
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.
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>
);
}
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.
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>
);
}
When you write custom components that need to access the map instance, you can use the useMap()
hook.
When you check out the repository you can view the example using the following command:
VITE_API_KEY=<yourApiKey> npm start
MIT