https://github.com/fgnass/googlemaps-react-primitives
Google Maps primitives for React
https://github.com/fgnass/googlemaps-react-primitives
googlemaps react
Last synced: 7 months ago
JSON representation
Google Maps primitives for React
- Host: GitHub
- URL: https://github.com/fgnass/googlemaps-react-primitives
- Owner: fgnass
- Created: 2022-02-03T16:40:47.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2023-10-23T14:28:19.000Z (over 2 years ago)
- Last Synced: 2025-06-23T23:50:32.336Z (9 months ago)
- Topics: googlemaps, react
- Language: TypeScript
- Homepage:
- Size: 549 KB
- Stars: 8
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# googlemaps-react-primitives
📍 Google Maps primitives for React
[](https://codesandbox.io/s/clever-bush-godk3)
## Rationale
When looking for a way to add Google Maps to a React application you'll find [tons](https://www.npmjs.com/package/google-map-react) of [different](https://www.npmjs.com/package/react-google-maps) solutions and [libraries](https://www.npmjs.com/package/@react-google-maps/api).
The idea behind this module is to stick to [Google's official guide for React](https://developers.google.com/maps/documentation/javascript/react-map) 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:
```tsx
import { Wrapper, Status } from "@googlemaps/react-wrapper";
import { GoogleMap } from "googlemaps-react-primitives";
function renderLoadingStatus(status: Status) {
return
{status}
;
}
function App() {
return (
);
}
```
To configure the map you can pass [all supported options](https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions) as props:
```tsx
```
## Map Markers
You can place standard markers on the map using the `Marker` component. It supports all [marker options](https://developers.google.com/maps/documentation/javascript/reference/marker#MarkerOptions) as props.
```tsx
import { GoogleMap, Marker } from "googlemaps-react-primitives";
function MyMap() {
return (
);
}
```
You can use this primitive to create a customized markers, for example to draw a custom path:
```tsx
function MyMarker(props: google.maps.MarkerOptions) {
return (
);
}
```
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:
```tsx
import { GoogleMap, SvgMarker } from "googlemaps-react-primitives";
function MyMap() {
return (
`}
/>
);
}
```
## Overlays
You can render arbitrary React component onto the map by using the `Overlay` component:
```tsx
import { GoogleMap, Overlay } from "googlemaps-react-primitives";
function MyMap() {
return (
Hello
World
);
}
```
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:
```tsx
interface Props {
position: google.maps.LatLngLiteral;
text: string;
}
function MyOverlay({ position, text }: Props) {
return (
{text}
);
}
```
**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 `` primitive:
```tsx
import { GoogleMap, Polyline } from "googlemaps-react-primitives";
function MyMap() {
return (
);
}
```
## Encoded Polylines
If you want to draw [encoded](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) polylines, you can use the `` primitive.
**NOTE:** Decoding requires the `geometry` library to be loaded:
```tsx
import { GoogleMap, EncodedPolyline } from "googlemaps-react-primitives";
function MyMap() {
return (
);
}
```
**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.
```tsx
import { GoogleMap, Marker } from "googlemaps-react-primitives";
function MyMap() {
return (
);
}
```
## 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= npm start`
# License
MIT