vue3-google-map

> 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.

Note: Please refer to the documentation site for rendered examples.

Table of Contents

• Getting Started
  • Installation
  • Your First Map
• Components
  • Advanced Marker
  • Marker
  • Polyline
  • Polygon
  • Rectangle
  • Circle
  • Info Window
  • Custom Marker
  • Custom Control
  • Marker Cluster
  • Heatmap Layer
• Advanced Usage
• Contribution
• License

Getting Started

Installation

NPM

npm install vue3-google-map
# OR
pnpm add vue3-google-map

CDN

Include the following script tag in your index.html (make sure to include it after Vue 3's global build).

All the map components are available on the Vue3GoogleMap global variable.

Codepen demo

Your First Map

To construct a map using vue3-google-map you'll need to use the base GoogleMap component which receives your Google Maps API key, styles (e.g. setting width and height), and any MapOptions to configure your map (see this for all the supported MapOptions). Other map features can be added to your map by passing map subcomponents (Marker, Polyline, Polygon, Rectangle, Circle, InfoWindow, CustomMarker, CustomControl, or MarkerCluster) to the default slot of the GoogleMap component.

<template>
  
    
</template>

Components

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:

• AdvancedMarker
• Marker
• Polyline
• Polygon
• Rectangle
• Circle
• InfoWindow
• CustomMarker
• CustomControl
• MarkerCluster

Advanced Marker

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 is necessary to specify a MapId on declaring the GoogleMap component (see more here).

Options

You can pass a AdvancedMarkerElementOptions object to the options prop to configure your marker.

You can also pass a PinElementOptions interface object to custumize pin used by the marker.

<template>
  
    
  
</template>

Events

You can listen for the following events on the AdvancedMarker component.

Marker

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.

<template>
  
    
</template>

Events

You can listen for the following events on the Marker component.

Polyline

Use the Polyline component to draw paths and arbitrary shapes on a map.

Options

You can pass a PolylineOptions object to the options prop to configure your polyline.

<template>
  
    
</template>

Events

You can listen for the following events on the Polyline component.

Polygon

Use the Polygon component to draw polgons (arbitrary number of sides) on a map.

Options

You can pass a PolylgonOptions object to the options prop to configure your polyline.

<template>
  
    
</template>

Events

You can listen for the following events on the Polygon component.

Rectangle

Use the Rectangle component to draw simple rectangles on a map.

Options

You can pass a RectangleOptions object to the options prop to configure your rectangle.

<template>
  
    
  
</template>

Events

You can listen for the following events on the Rectangle component.

Circle

Use the Circle component to draw circles on a map.

Options

You can pass a CircleOptions object to the options prop to configure your circle.

<template>
  
    
</template>

Events

You can listen for the following events on the Circle component.

Info Window

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.

<template>
  
    
    
      Content passed through slot
    
  
</template>

Use with Marker

You can nest the InfoWindow component inside the Marker component to display an info window when the marker is clicked.

<template>
  
    
  
</template>

Open and close the Info Window

You can use v-model to manage the state of the info window programmatically or to know whether it's open or closed

<template>
  
    
  
</template>

Events

You can listen for the following events on the InfoWindow component.

Custom Marker

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.

<template>
  
    
      <div style="text-align: center">
        <div style="font-size: 1.125rem">Vuejs Amsterdam</div>
        <img style="margin-top: 8px" height="50" width="50" src="https://vuejs.org/images/logo.png">
      </div>
    
  
</template>

Custom Control

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.

Refer to the Google Maps documentation on custom controls positioning.

<template>
  
    
      <button class="custom-btn">👋</button>
    
  
</template>

<style>
.custom-btn {
  box-sizing: border-box;
  background: white;
  height: 40px;
  width: 40px;
  border-radius: 2px;
  border: 0px;
  margin: 10px;
  padding: 0px;
  font-size: 1.25rem;
  text-transform: none;
  appearance: none;
  cursor: pointer;
  user-select: none;
  box-shadow: rgba(0, 0, 0, 0.3) 0px 1px 4px -1px;
  overflow: hidden;
}
</style>

Marker Cluster

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.

<template>
  
    
      
  
</template>

Options

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.

Events

You can listen for the following events on the MarkerCluster component.

Heatmap Layer

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.

<template>
  
    
  
</template>

Advanced Usage

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).

Usage Patterns

<template>
  
    <template>
      
    </template>
  
</template>

Example:

<template>
  
  <label for="lng">Longitude</label>
  <input step="10" max="180" min="-180" type="number" id="lng">
</template>

<style>
.map {
  position: relative;
  width: 100%;
  height: 500px;
}

.map::after {
  position: absolute;
  content: '';
  width: 1px;
  height: 100%;
  top: 0;
  left: 50%;
  background: red;
}

label {
  font-weight: 500;
}

input[type='number'] {
  margin-top: 20px;
  margin-left: 10px;
  outline: 1px solid #ccc;
  border-radius: 4px;
}
</style>

Loading the Google Maps API script externally

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.

<template>
  
    
</template>

Contribution

All contributions are welcome. Before submitting a PR though it would be nice if you created an issue explaining what you want to acheive and why.

License

MIT