!Build Status !CI Status  
> Composable components for easy use of Google Maps with Vue 3
vue3-google-map offers a set of composable components for easy use of Google Maps in your Vue 3 projects.
This library is intended to be used in a composable fashion. Therefore you will find yourself using nested components to build your map rather than just a complicated inline format.
The main mapping component is GoogleMap, however the following components are available at your disposal:
Use the AdvancedMarker component to draw markers, drop pins or any custom icons on a map. AdvancedMarker is the new version offered by google when deprecated the Marker component (read more here).
In order to use the AdvancedMarker component it is necessary to specify a MapId on declaring the GoogleMap component (see more here).
> [!IMPORTANT] > If you're using the AdvancedMarker component with an external loader (using the apiPromise prop), you must include the marker library: > > `js > import { setOptions, importLibrary } from '@googlemaps/js-api-loader'; > > setOptions({ > key: YOUR_GOOGLE_MAPS_API_KEY, > v: 'weekly', > }); > > const apiPromise = Promise.all([ > importLibrary('maps'), > importLibrary('marker'), // Required for AdvancedMarker component > ]).then(() => window.google); > `
> [!WARNING] > DEPRECATED: The Marker component is deprecated as of February 2024. Please use the AdvancedMarker component instead for new projects. The legacy google.maps.Marker API will be removed in a future version. Learn more about the deprecation.
Use the Marker component to draw markers, drop pins or any custom icons on a map.
#### Options
You can pass a MarkerOptions object to the options prop to configure your marker.
Use the InfoWindow component to display content in a popup window above the map, at a given location.
#### Options
You can pass an InfoWindowOptions object to the options prop to configure your info window. Note that you can optionally pass your content to the default slot of the InfoWindow component.
Uluru, also referred to as Ayers Rock, is a large sandstone rock formation in the southern part of the Northern Territory, central Australia. It lies 335 km (208 mi) south west of the nearest large town, Alice Springs; 450 km (280 mi) by road. Kata Tjuta and Uluru are the two major features of the Uluru - Kata Tjuta National Park. Uluru is sacred to the Pitjantjatjara and Yankunytjatjara, the Aboriginal people of the area. It has many springs, waterholes, rock caves and ancient paintings. Uluru is listed as a World Heritage Site.
Regular markers can be customized a great deal but if you need to you can use the CustomMarker component and provide your own custom markup through it's default slot.
#### Options
| Parameter | Type | Description | | :-------- | :------- | :------------------------- | | position | { lat: number, lng: number} | Sets the marker position. | | anchorPoint | 'CENTER' \| 'TOP_CENTER' \|'BOTTOM_CENTER' \| 'LEFT_CENTER' \| 'RIGHT_CENTER' \| 'TOP_LEFT' \| 'TOP_RIGHT' \| 'BOTTOM_LEFT' \| 'BOTTOM_RIGHT' | Sets how the marker is anchored relative to it's position point. Default is CENTER. | | offsetX | number | Horizontal offset from the position point. | | offsetY | number | Vertical offset from the position point. | | zIndex | number | z-index value of the marker. |
Use the CustomControl component to add custom buttons/controls to your map.
#### Usage
You can define the markup of your custom control in the default slot of the CustomControl component. The component itself takes two props:
- position: Defines the position of your custom control on the map. Its value must be one of the ControlPosition constants. - index (optional): Controls the order of placement for custom controls that occupy the same position.
Use the MarkerCluster component to display a large number of markers on a map. It will combine markers of close proximity into clusters, and simplify the display of markers on the map. Can be used with the Marker or CustomMarker components.
#### Usage
Simply pass your Marker/CustomMarker(s) in the default slot of the MarkerCluster component.
MarkerCluster accepts an options prop (an object) where you can configure algorithm, onClusterClick, and renderer from the MarkerClustererOptions interface. Note that all these options are completely optional but non-reactive.
MarkerCluster uses debounced rendering to improve performance when adding or removing markers. Instead of rendering after every marker operation, it batches multiple operations together and renders once after a short delay.
The renderDebounceDelay prop controls the debounce delay in milliseconds (default: 10). For immediate rendering, access the underlying clusterer via a template ref and call render():
`vue
`
$3
> [!WARNING] > DEPRECATED: The HeatmapLayer component was deprecated on May 27, 2025 and will be sunset in May 2026. Google recommends migrating to third-party library integrations like deck.gl, which offers a HeatmapLayer implementation. Learn more about the deprecation.
Use the HeatmapLayer component to depict the intensity of data at geographical points on the map. Make sure to include the visualization library in the libraries prop of the GoogleMap component.
#### Options
You can pass a HeatmapLayerOptions object to the options prop to configure your heatmap layer. Note that for convenience you can use LatLngLiterals if you wish for the locations.
The basic components that vue3-google-map provides are fully reactive and will get you pretty far. Should you need to access the Google Maps API, however, the GoogleMap component exposes the following:
- ready: A boolean indicating when the Google Maps script has been loaded. By this point the map instance has been created, the API is ready for use and event listeners have been set up on the map. - map: The Map class instance. - api: The Google Maps API. - mapTilesLoaded: A boolean indicating when the map tiles have been fully loaded.
In addition, most of the subcomponents expose their instance should you need it:
- Marker exposes marker (a Marker class instance). - Polyline exposes polyline (a Polyline class instance). - Polygon exposes polygon (a Polygon class instance). - Rectangle exposes rectangle (a Rectangle class instance). - Circle exposes circle (a Circle class instance). - InfoWindow exposes infoWindow (an InfoWindow class instance). - MarkerCluster exposes markerCluster (a MarkerClusterer class instance). - HeatmapLayer exposes heatmapLayer (a HeatmapLayer class instance).
By default you would pass your API key as a prop to the GoogleMap component and it handles the loading of the Google Maps API script for you. There are cases, however, where you might want to load the script yourself. For example, you might be using other Google Maps components or your Vue app might be a part of a larger app that uses the Google Maps API elsewhere. In these cases you can use the apiPromise prop to pass a promise that resolves to the Google Maps API global google object.
