x5-gmaps (Live Demo)
This is a lightweight Google Maps plugin for Vue.
Also check out a tutorial creating a COVID Heatmap using this.
# npm
npm install x5-gmaps
This plugin can be installed like any Vue plugin:
import x5GMaps from 'x5-gmaps'
// Option 1: Just your key
Vue.use(x5GMaps, 'YOUR_GOOGLE_KEY')
// Option 2: With libraries
Vue.use(x5GMaps, { key: 'YOUR_GOOGLE_KEY', libraries: ['places'] })
new Vue({
el: '#app',
render: (h) => h(App),
})
vue.config.js
file:
module.exports = {
transpileDependencies: ['x5-gmaps'],
}
<template>
<gmaps-map>
<gmaps-marker :position="{ lat: -27, lng: 153 }" />
</gmaps-map>
</template>
import { gmapsMap, gmapsMarker } from 'x5-gmaps'
export default {
components: { gmapsMap, gmapsMarker },
}
Some pre-built components have been provided for general use, or as examples for those who wish to take them further.
Maps can take many options. zoom
is defaulted to 12
and center
is defaulted to Brisbane (as these options are required).
This component supports the following events:
@boundsChanged
returns new bounds@centerChanged
returns new center@click
returns event@doubleClick
returns event@rightClick
returns event@mouseover
returns event@mouseout
returns event
<template>
<gmaps-map :options="mapOptions" />
</template>
<script>
import { gmapsMap } from 'x5-gmaps'
export default {
components: { gmapsMap },
data: () => ({
mapOptions: {
center: { lat: -27.47, lng: 153.025 },
zoom: 12,
},
}),
}
</script>
Markers are placed within Maps and can take many options. A position
option is required within the options prop or as its own prop.
This component supports the following events:
@move
returns new position { lat, lng }@click
returns event@doubleClick
returns event@rightClick
returns event(depreciated) returns new position@positionChanged
Props | Type | Default | Description |
---|---|---|---|
options* | Object | - | An object of Google Maps Marker options |
icon | String | - | URL of the marker icon to be used |
label | String | - | Marker label |
opacity | Number | 1.0 |
Opacity of the marker |
position | Object | - | An object that has lat and lng properties |
title | String | - | Marker title (shown on hover) |
visible | Boolean | true |
If marker is visible |
zIndex | Number | - | Override position in DOM |
* If you want to change values on the fly, use the named props instead of within the options prop. Changing named props will trigger an update.
<template>
<gmaps-map>
<gmaps-marker v-for="(item, i) in items" :key="i" :options="item.options" />
</gmaps-map>
</template>
<script>
import { gmapsMap, gmapsMarker } from 'x5-gmaps'
export default {
components: { gmapsMap, gmapsMarker },
data: () => ({
items: [
{ options: { position: { lat: -27.41, lng: 153.01 } } },
{ options: { position: { lat: -27.42, lng: 153.02 } } },
...,
{ options: { position: { lat: -27.48, lng: 153.08 } } },
{ options: { position: { lat: -27.49, lng: 153.09 } } },
],
}),
}
</script>
InfoWindows are placed with Maps can take a few options. A position
option is required.
They are used to put HTML in and have a close/dismiss button built-in.
This component only supports a @closed
event (for when someone closes the window)
<template>
<gmaps-map :options="mapOptions">
<gmaps-info-window :options="options">
<p>Example Text</p>
</gmaps-info-window>
</gmaps-map>
</template>
<script>
import { gmapsMap, gmapsInfoWindow } from 'x5-gmaps'
export default {
components: { gmapsMap, gmapsInfoWindow },
data: () => ({
options: {
position: { lat: -27.46, lng: 153.02 },
},
mapOptions: {
center: { lat: -27.47, lng: 153.025 },
zoom: 12,
},
}),
}
</script>
A Popup is a custom DOM Element. It is here primarily as an example of what is needed when creating your own map objects, but serves as a cleaner InfoWindow for Vue.
It takes the following props:
position
(req'd)background
(style)height
(style)width
(style)
All events are registered from the markup/component you place inside it rather than the popup itself.
<template>
<gmaps-map :options="mapOptions">
<gmaps-popup :position="position" background="#BBF0FF">
<span @click="doSomething()">Do Something</span>
</gmaps-popup>
</gmaps-map>
</template>
<script>
import { gmapsMap, gmapsPopup } from 'x5-gmaps'
export default {
components: { gmapsMap, gmapsPopup },
data: () => ({
position: { lat: -27.46, lng: 153.02 },
mapOptions: {
center: { lat: -27.47, lng: 153.025 },
zoom: 12,
},
}),
}
</script>
Heatmaps are placed within Maps and have several props which are derived from Google's Heatmap Options. Some are named differently as they have been enhanced/simplified.
Props | Type | Default | Description |
---|---|---|---|
items | Array<Object> | required | An array of objects that has lat and lng properties |
colors | Array<String> | - | An array of one or more colors to color heatmap e.g. ['red','#0F0','rgba(0,0,0,0)`] |
dissipating | Boolean | true |
Specifies whether heatmaps dissipate on zoom |
opacity | Number | 0.6 |
Opacity of the heatmap |
maxIntensity | Number | - | Number of points in one spot to reach "maximum heat" color |
radius | Number | - | The radius of influence for each data point, in pixels |
weightProp | String | - | The property of items that should be used as the weight (Numbers > 0) |
This component does not have any events.
** Note require to include the "visualization" library as described in Deployment
<template>
<gmaps-map>
<gmaps-heatmap :data="items" :opacity="0.8" />
</gmaps-map>
</template>
<script>
import { gmapsMap, gmapsHeatmap } from 'x5-gmaps'
export default {
components: { gmapsMap, gmapsHeatmap },
data: () => ({
items: [
{ lat: -27.41, lng: 153.01 },
{ lat: -27.42, lng: 153.02 },
...,
{ lat: -27.48, lng: 153.08 },
{ lat: -27.49, lng: 153.09 },
],
}),
}
</script>
Polylines/polygons are placed within Maps and have several props which are derived from Google's Polyline Options and Polygon Options.
This component supports the following events:
@click
returns PolyMouseEvent@doubleClick
returns PolyMouseEvent@drag
returns MouseEvent@dragEnd
returns MouseEvent@dragStart
returns MouseEvent@mouseover
returns PolyMouseEvent@rightClick
returns PolyMouseEvent
Props | Type | Default | Description |
---|---|---|---|
clickable | Boolean | true |
Indicates whether this Polyline handles mouse events |
draggable | Boolean | false |
Allow the shape to be dragged over the map |
editable | Boolean | false |
Allow editing the shape by dragging the control points |
fillColor | String | black | (Only polygons) The fill color *** |
fillOpacity | Number | 0.3 |
(Only polygons) The fill opacity between 0.0 and 1.0 |
geodesic | Boolean | false |
When true, lines will follow the curvature of the Earth |
icons | Array | [] | (Only polylines) Add icons along your path ** |
path | Array | required | Path points (objects with lat and lng properties) |
strokeColor | String | black | The stroke color *** |
strokePosition | Number | 0 |
(Only polygons) The stroke position along the path (0 = CENTER / 1 = INSIDE / 2 = OUTSIDE) |
strokeOpacity | Number | 1.0 |
The stroke opacity between 0.0 and 1.0 |
strokeWeight | Number | - | The stroke width in pixels |
visible | Boolean | true |
Whether this polyline is visible on the map |
zIndex | Number | 0 |
The zIndex compared to other polys |
** Note this is one of those things you're surprised Google couldn't do right. It doesn't take images like all the rest of the icon properties of other components. Here's their example
*** All CSS3 colors are supported except for extended named colors
<template>
<gmaps-map>
<gmaps-polygon :path="items" :strokeColor="blue" :fillColor="red" />
<gmaps-polyline :path="items" :strokeColor="blue" />
</gmaps-map>
</template>
<script>
import { gmapsMap, gmapsPolyline, gmapsPolygon } from 'x5-gmaps'
export default {
components: { gmapsMap, gmapsPolyline, gmapsPolygon },
data: () => ({
items: [
{ lat: -27.41, lng: 153.01 },
{ lat: -27.42, lng: 153.02 },
...,
{ lat: -27.48, lng: 153.08 },
{ lat: -27.49, lng: 153.09 },
],
}),
}
</script>
Rectangles/circles are placed within Maps and have several props which are derived from Google's Rectangle Options and Circle Options.
This component supports the following events:
@boundsChanged
(Only rectangles) returns new bounds@centerChanged
(Only circles) returns new center@radiusChanged
(Only circles) returns new radius@click
returns PolyMouseEvent@doubleClick
returns PolyMouseEvent@drag
returns MouseEvent@dragEnd
returns MouseEvent@dragStart
returns MouseEvent@mouseover
returns PolyMouseEvent@rightClick
returns PolyMouseEvent
Props | Type | Default | Description |
---|---|---|---|
bounds | Array | required | (Only rectangles) Position of your rectangle { east, north, south, west } |
center | Object | required | (Only circles) The center of the Circle (object with lat and lng properties) |
radius | Number | required | (Only circles) The radius in meters on the Earth's surface |
clickable | Boolean | true |
Indicates whether this Polyline handles mouse events |
draggable | Boolean | false |
Allow the shape to be dragged over the map |
editable | Boolean | false |
Allow editing the shape by dragging the control points |
fillColor | String | black | The fill color *** |
fillOpacity | Number | 0.3 |
The fill opacity between 0.0 and 1.0 |
strokeColor | String | black | The stroke color *** |
strokePosition | Number | 0 |
The stroke position along the path (0 = CENTER / 1 = INSIDE / 2 = OUTSIDE) |
strokeOpacity | Number | 1.0 |
The stroke opacity between 0.0 and 1.0 |
strokeWeight | Number | - | The stroke width in pixels |
visible | Boolean | true |
Whether this polyline is visible on the map |
zIndex | Number | 0 |
The zIndex compared to other polys |
*** All CSS3 colors are supported except for extended named colors
<template>
<gmaps-map>
<gmaps-rectangle :bounds="bounds" :strokeColor="blue" :fillColor="red" />
<gmaps-circle :center="center" :radius="radius" :strokeColor="green" :fillColor="yellow" />
</gmaps-map>
</template>
<script>
import { gmapsMap, gmapsRectangle, gmapsCircle } from 'x5-gmaps'
export default {
components: { gmapsMap, gmapsPolyline, gmapsPolygon },
data: () => ({
bounds: {
east: 153.12,
north: -27.44,
west: 153.0,
south: -27.58,
},
center: { lat: -27.479, lng: 152.937 },
radius: 5000,
}),
}
</script>
While you shouldn't see these for too long, if at all, there are two customisable slots: Loading and Error.
<template>
<gmaps-map>
<template v-slot:loading>
<div>
<span>This is now loading...</span>
</div>
</template>
<template v-slot:error="{ error }">
<div>
<span>You broke it: {{ error }}</span>
</div>
</template>
</gmaps-map>
</template>
Please read CONTRIBUTING.md for the process for submitting pull requests.
This project is licensed under the MIT License - see the LICENSE.md file for details