New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
@vis.gl/react-google-maps
Advanced tools
@vis.gl/react-google-maps - npm Package Compare versions
Comparing version 0.1.0 to 0.1.2
@@ -1084,3 +1084,3 @@ (function (global, factory) { | ||
| map = _ref2.map; | ||
| // if an if is specified, the corresponding map or null is returned | ||
| // if an id is specified, the corresponding map or null is returned | ||
| if (id !== null) return mapInstances[id] || null; | ||
@@ -1087,0 +1087,0 @@ // otherwise, return the closest ancestor |
| { | ||
| "name": "@vis.gl/react-google-maps", | ||
| "version": "0.1.0", | ||
| "version": "0.1.2", | ||
| "description": "React components and hooks for Google Maps.", | ||
@@ -5,0 +5,0 @@ "source": "src/index.ts", |
196
README.md
@@ -5,36 +5,32 @@ # React Components for the Google Maps JavaScript API | ||
| A library to integrate the Google Maps JavaScript API into React Applications | ||
| using simple components or hooks. | ||
| This is a TypeScript / JavaScript library to integrate the Maps JavaScript API | ||
| into your React application. | ||
| It comes with a collection of React components to create maps, markers and | ||
| infowindows, and a set of hooks to use some of the Maps JavaScript API | ||
| [Services][gmp-services] and [Libraries][gmp-libraries]. | ||
| The hooks provide the possibility to access different Google Maps Platform services and libraries, as well as the map instance | ||
| itself inside all components that are wrapped inside the `APIProvider`. | ||
| The map instance can only be accessed, if a `Map` component is used inside the `APIProvider`. | ||
| ## Description | ||
| This is a Typescript / JavaScript library to integrate the Maps JavaScript API into your React application. | ||
| It comes with a collection of React components to create maps, markers and infowindows, and a set of | ||
| hooks to use some of the Maps JavaScript | ||
| API [Services](https://developers.google.com/maps/documentation/javascript#services) | ||
| and [Libraries](https://developers.google.com/maps/documentation/javascript/libraries). | ||
| ## Installation | ||
| This library is available via npm as the package [@vis.gl/react-google-maps](https://www.npmjs.com/package/@vis.gl/react-google-maps). | ||
| This library is available on npm as [`@vis.gl/react-google-maps`][npm-package]. | ||
| ```sh | ||
| npm install --save @vis.gl/react-google-maps -D | ||
| npm install @vis.gl/react-google-maps | ||
| ``` | ||
| ## Map Usage | ||
| ## Usage | ||
| Import the `APIProvider` and wrap it around all components that should have access to the map instance(s). | ||
| All components that are children of the `APIProvider` can use hooks, components and access all map instance(s). | ||
| Import the [`APIProvider`][api-provider] and wrap it around all components that should have | ||
| access to the Google Maps API. | ||
| Any component within the context of the `APIProvider` can use the hooks and | ||
| components provided by this library. | ||
| Add a `Map` component inside the `APIProvider` to display a map on the screen. Inside the `Map` component, it is | ||
| possible to add components like a `Marker` or `InfoWindow` that can be displayed on the map. Also, all hooks can be used | ||
| inside all components. | ||
| To render a simple map, add a [`Map`][api-map] component inside the `APIProvider`. | ||
| Within the `Map` component, you can then add further components like | ||
| [`Marker`][api-marker], [`AdvancedMarker`][api-adv-marker], or | ||
| [`InfoWindow`][api-infowindow] to render content on the map. | ||
| For more advanced use-cases you can even add your own components to the map | ||
| that make use of `google.maps.OverlayView` or `google.maps.WebGlOverlayView`. | ||
| ```tsx | ||
| import React from 'react'; | ||
| import {APIProvider, Map, Marker} from '@vis.gl/react-google-maps'; | ||
@@ -57,96 +53,18 @@ | ||
| ## Usage of the `useMap` hook | ||
| Please see our [documentation][docs] or [examples][] for more in-depth information | ||
| about this library. | ||
| The `APIProvider` is used to load the Maps JavaScript API at the top level of the app component and provides a | ||
| context that holds all map instances that can be accessed via the `useMap` hook. | ||
| ### Using other libraries of the Maps JavaScript API | ||
| It is possible to use one or multiple `Map` components inside the `APIProvider`. | ||
| Make sure to pass the id of the map to the `useMap` hook when using multiple maps. | ||
| Besides rendering maps, the Maps JavaScript API has a lot of | ||
| [additional libraries][gmp-libraries] for things like geocoding, routing, the | ||
| Places API, Street View, and a lot more. | ||
| These libraries are not loaded by default, which is why this module provides | ||
| the [`useMapsLibrary()`][api-use-lib] hook to handle dynamic loading of | ||
| additional libraries. | ||
| ### Hook usage with one Map component | ||
| For example, if you want to use the `google.maps.places.PlacesService` class in | ||
| your component, you can implement it like this: | ||
| The `useMap()` hook can be used to directly access the `google.maps.Map` instance created by a `<Map>` component | ||
| in your application. | ||
| ```tsx | ||
| import React, {useEffect} from 'react'; | ||
| import {APIProvider, useMap} from '@vis.gl/react-google-maps'; | ||
| const MyComponent = () => { | ||
| const map = useMap(); | ||
| useEffect(() => { | ||
| if (!map) return; | ||
| // here you can interact with the imperative maps API | ||
| }, [map]); | ||
| return <></>; | ||
| }; | ||
| const App = () => ( | ||
| <APIProvider apiKey={'YOUR API KEY HERE'}> | ||
| <Map /* ... */></Map> | ||
| <MyComponent /> | ||
| </APIProvider> | ||
| ); | ||
| ``` | ||
| ### Hook usage with multiple Map components | ||
| When multiple `Map` components are used, an additional prop `id` is required for all map components (internally, the | ||
| id `default` is used whenever no map-id is specified, which could lead to problems with multiple maps). | ||
| Inside the App component: | ||
| ```tsx | ||
| import React from 'react'; | ||
| import {APIProvider, Map} from '@vis.gl/react-google-maps'; | ||
| function App() { | ||
| const position = {lat: 53.54992, lng: 10.00678}; | ||
| return ( | ||
| <APIProvider apiKey={'YOUR API KEY HERE'}> | ||
| <Map id={'map-1'} /* ... */ /> | ||
| <Map id={'map-2'} /* ... */ /> | ||
| </APIProvider> | ||
| ); | ||
| } | ||
| export default App; | ||
| ``` | ||
| Inside another component, accessing the map instances: | ||
| ```tsx | ||
| import React, {useEffect} from 'react'; | ||
| import {useMap} from '@vis.gl/react-google-maps'; | ||
| const MyComponent = () => { | ||
| const mapOne = useMap('map-1'); | ||
| const mapTwo = useMap('map-2'); | ||
| useEffect(() => { | ||
| if (!mapOne || !mapTwo) return; | ||
| // interact with the map-instances. | ||
| }, [mapOne, mapTwo]); | ||
| return <></>; | ||
| }; | ||
| ``` | ||
| ## Using other libraries of the Google Maps JavaScript API | ||
| Besides rendering maps, the Maps JavaScript API has a lot of [additional libraries](https://developers.google.com/maps/documentation/javascript/libraries) | ||
| for things like geocoding, routing, the Places API, Street View, and a lot more. These libraries | ||
| are not loaded by default, which is why this module provides a hook | ||
| `useMapsLibrary()` to handle dynamic loading of those libraries. | ||
| For example, if you want to write a component that needs to use the | ||
| `google.maps.places.PlacesService` class, you can implement it like this: | ||
| ```tsx | ||
| import {useMapsLibrary} from '@vis.gl/react-google-maps'; | ||
@@ -158,12 +76,10 @@ | ||
| // the case) | ||
| const placesApiLoaded = useMapsLibrary('places'); | ||
| const placesLib = useMapsLibrary('places'); | ||
| const [placesService, setPlacesService] = useState(null); | ||
| useEffect(() => { | ||
| if (!placesApiLoaded) return; | ||
| if (!placesLib) return; | ||
| // when placesApiLoaded is true, the library can be accessed via the | ||
| // global `google.maps` namespace. | ||
| setPlacesService(new google.maps.places.PlacesService()); | ||
| }, [placesApiLoaded]); | ||
| setPlacesService(new placesLib.PlacesService()); | ||
| }, [placesLib]); | ||
@@ -180,33 +96,17 @@ useEffect(() => { | ||
| Or you can extract your own hook from this: | ||
| ## Examples | ||
| ```tsx | ||
| function usePlacesService() { | ||
| const placesApiLoaded = useMapsLibrary('places'); | ||
| const [placesService, setPlacesService] = useState(null); | ||
| Explore our [examples directory on GitHub](./examples) or the | ||
| [examples on our website][examples] for full implementation examples. | ||
| useEffect(() => { | ||
| if (!placesApiLoaded) return; | ||
| setPlacesService(new google.maps.places.PlacesService()); | ||
| }, [placesApiLoaded]); | ||
| return placesService; | ||
| } | ||
| const MyComponent = () => { | ||
| const placesService = usePlacesService(); | ||
| useEffect(() => { | ||
| if (!placesService) return; | ||
| // ... use placesService ... | ||
| }, [placesService]); | ||
| return <></>; | ||
| }; | ||
| ``` | ||
| ## Examples | ||
| Explore our [examples directory on GitHub](./examples) for full implementation examples. | ||
| [api-provider]: https://visgl.github.io/react-google-maps/docs/api-reference/components/api-provider | ||
| [api-map]: https://visgl.github.io/react-google-maps/docs/api-reference/components/map | ||
| [api-marker]: https://visgl.github.io/react-google-maps/docs/api-reference/components/marker | ||
| [api-adv-marker]: https://visgl.github.io/react-google-maps/docs/api-reference/components/advanced-marker | ||
| [api-infowindow]: https://visgl.github.io/react-google-maps/docs/api-reference/components/info-window | ||
| [api-use-lib]: https://visgl.github.io/react-google-maps/docs/api-reference/hooks/use-maps-library | ||
| [docs]: https://visgl.github.io/react-google-maps/docs/ | ||
| [examples]: https://visgl.github.io/react-google-maps/examples | ||
| [gmp-services]: https://developers.google.com/maps/documentation/javascript#services | ||
| [gmp-libraries]: https://developers.google.com/maps/documentation/javascript/libraries | ||
| [npm-package]: https://www.npmjs.com/package/@vis.gl/react-google-maps |
@@ -15,3 +15,3 @@ import {useContext} from 'react'; | ||
| // if an if is specified, the corresponding map or null is returned | ||
| // if an id is specified, the corresponding map or null is returned | ||
| if (id !== null) return mapInstances[id] || null; | ||
@@ -18,0 +18,0 @@ |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
No alert changes
Worsened metrics
- Total package byte prevSize
- decreased by-0.65%
327960
- Number of lines in readme file
- decreased by-47.85%
109
No dependency changes