|
| 1 | +# Google Maps React |
| 2 | + |
| 3 | +[](https://github.com/ubilabs/google-maps-react-hooks/tree/main/LICENSE) |
| 4 | + |
| 5 | +A library to integrate the Google Maps JavaScript API into React Applications |
| 6 | +using simple components or hooks. |
| 7 | + |
| 8 | +The hooks provide the possibility to access different Google Maps services and libraries, as well as the map instance |
| 9 | +itself inside all components that are wrapped inside the `APIProvider`. |
| 10 | +The map instance can only be accessed, if a `Map` component is used inside the `APIProvider`. |
| 11 | + |
| 12 | +## Description |
| 13 | + |
| 14 | +This is a Typescript / Javascript library to integrate the Google Maps Javascript API into your React application. |
| 15 | +It comes with a collection of React components to create maps, markers and infowindows, and a set of |
| 16 | +hooks to use some of the Google Maps |
| 17 | +API [Services](https://developers.google.com/maps/documentation/javascript#services) |
| 18 | +and [Libraries](https://developers.google.com/maps/documentation/javascript#libraries). |
| 19 | + |
| 20 | +## Installation |
| 21 | + |
| 22 | +```sh |
| 23 | +npm install @vis.gl/react-google-maps -D |
| 24 | +``` |
| 25 | + |
| 26 | +## Map Usage |
| 27 | + |
| 28 | +Import the `APIProvider` and wrap it around all components that should have access to the map instance(s). |
| 29 | +All components that are children of the `APIProvider` can use hooks, components and access all map instance(s). |
| 30 | + |
| 31 | +Add a `Map` component inside the `APIProvider` to display a map on the screen. Inside the `Map` component, it is |
| 32 | +possible to add components like a `Marker` or `InfoWindow` that can be displayed on the map. Also, all hooks can be used |
| 33 | +inside all components. |
| 34 | + |
| 35 | +```tsx |
| 36 | +import React from 'react'; |
| 37 | +import {APIProvider, Map, Marker, InfoWindow} from '@vis.gl/react-google-maps'; |
| 38 | + |
| 39 | +function App() { |
| 40 | + const position = {lat: 53.54992, lng: 10.00678}; |
| 41 | + |
| 42 | + return ( |
| 43 | + <APIProvider googleMapsAPIKey={'YOUR API KEY HERE'}> |
| 44 | + <Map zoom={10} center={position}> |
| 45 | + <Marker position={position}> |
| 46 | + <InfoWindow> |
| 47 | + <p>I am open.</p> |
| 48 | + </InfoWindow> |
| 49 | + </Marker> |
| 50 | + </Map> |
| 51 | + </APIProvider> |
| 52 | + ); |
| 53 | +} |
| 54 | + |
| 55 | +export default App; |
| 56 | +``` |
| 57 | + |
| 58 | +## Usage of the `useGoogleMap` hook |
| 59 | + |
| 60 | +The `APIProvider` is used to load the Google Maps JavaScript API at the top level of the app component and provides a |
| 61 | +context that holds all map instances that can be accessed via the `useGoogleMap` hook. |
| 62 | + |
| 63 | +It is possible to use one or multiple `Map` components inside the `APIProvider`. Make sure to pass the id of the map to |
| 64 | +the `useGoogleMap` hook when using multiple maps. |
| 65 | + |
| 66 | +### Hook usage with one Map component |
| 67 | + |
| 68 | +The `useGoogleMap()` hook can be used to directly access the `google.maps.Map` instance created by a `<Map>` component |
| 69 | +in your application. |
| 70 | + |
| 71 | +```tsx |
| 72 | +import React, {useEffect} from 'react'; |
| 73 | +import {APIProvider, useGoogleMap} from '@vis.gl/react-google-maps'; |
| 74 | + |
| 75 | +const MyComponent = () => { |
| 76 | + const map = useGoogleMap(); |
| 77 | + |
| 78 | + useEffect(() => { |
| 79 | + if (!map) return; |
| 80 | + |
| 81 | + // here you can interact with the imperative maps API |
| 82 | + }, [map]); |
| 83 | + |
| 84 | + return <></>; |
| 85 | +}; |
| 86 | + |
| 87 | +const App = () => ( |
| 88 | + <APIProvider apiKey={'YOUR API KEY HERE'}> |
| 89 | + <Map /* ... */></Map> |
| 90 | + |
| 91 | + <MyComponent /> |
| 92 | + </APIProvider> |
| 93 | +); |
| 94 | +``` |
| 95 | + |
| 96 | +### Hook usage with multiple Map components |
| 97 | + |
| 98 | +When multiple `Map` components are used, an additional prop `id` is required for all map components (internally, the |
| 99 | +id `default` is used whenever no map-id is specified, which could lead to problems with multiple maps). |
| 100 | + |
| 101 | +Inside the App component: |
| 102 | + |
| 103 | +```tsx |
| 104 | +import React from 'react'; |
| 105 | +import {APIProvider, Map} from '@vis.gl/react-google-maps'; |
| 106 | + |
| 107 | +function App() { |
| 108 | + const position = {lat: 53.54992, lng: 10.00678}; |
| 109 | + |
| 110 | + return ( |
| 111 | + <APIProvider apiKey={'YOUR API KEY HERE'}> |
| 112 | + <Map id={'map-1'} /* ... */ /> |
| 113 | + <Map id={'map-2'} /* ... */ /> |
| 114 | + </APIProvider> |
| 115 | + ); |
| 116 | +} |
| 117 | + |
| 118 | +export default App; |
| 119 | +``` |
| 120 | + |
| 121 | +Inside another component, accessing the map instances: |
| 122 | + |
| 123 | +```tsx |
| 124 | +import React, {useEffect} from 'react'; |
| 125 | +import {useGoogleMap} from '@vis.gl/react-google-maps-hooks'; |
| 126 | + |
| 127 | +const MyComponent = () => { |
| 128 | + const mapOne = useGoogleMap('map-1'); |
| 129 | + const mapTwo = useGoogleMap('map-2'); |
| 130 | + |
| 131 | + useEffect(() => { |
| 132 | + if (!mapOne || !mapTwo) return; |
| 133 | + |
| 134 | + // interact with the map-instances. |
| 135 | + }, [mapOne, mapTwo]); |
| 136 | + |
| 137 | + return <></>; |
| 138 | +}; |
| 139 | +``` |
| 140 | + |
| 141 | +## Examples |
| 142 | + |
| 143 | +Explore |
| 144 | +our [examples directory on GitHub](https://github.com/ubilabs/internal-google-maps-react-hooks-copy/tree/main/packages/examples) |
| 145 | +for full implementation examples. |
0 commit comments