x5-gmaps (Live Demo)

This is a lightweight Google Maps plugin for Vue 2 Now with Typescript! 🥳

Samples/examples/tutorials

• These use slightly older versions of this package but are similar enough for you to get the idea. Read below for the latest on how to use each component.

• Tutorial creating a COVID Heatmap
• Address Autocomplete Example

Installation

# npm
npm install x5-gmaps

Deployment

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)
});

If you're using Typescript, you will need to add the Types into your tsconfig.json file as you would any other library.

{
  "compilerOptions": {
    "types": [
      "x5-gmaps"
    ]
  }
}

For Quasar, because you cannot use Vue.use(), in a boot file you can import the default export as 'install' and run that with the Vue instance and options as the parameters:

import { install } from 'x5-gmaps';

export default async ({ Vue }) => {
  install(Vue, 'XXXXXX');
  // install(Vue, { key: "XXXXXX", libraries: ["places"] });
};

⚠️ This plugin is not transpiled! If you want it compatible with IE, Edge, and Safari, you need to add this to your vue.config.js file:

module.exports = {
  transpileDependencies: ['x5-gmaps']
};

Usage

<template>
  <gmaps-map>
    <gmaps-marker :position="{ lat: -27, lng: 153 }" />
  </gmaps-map>
</template>

import { gmapsMap, gmapsMarker } from 'x5-gmaps';

export default {
  components: { gmapsMap, gmapsMarker }
};

Provided Components

Some pre-built components have been provided for general use, or as examples for those who wish to take them further.

Map

Maps can take many options. zoom is defaulted to 12 and center is defaulted to Brisbane (as these options are required). The type of these is google.maps.MapOptions.

This component supports the following events:

• @bounds-changed returns new bounds
• @center-changed returns new center
• @zoom-changed returns new zoom level
• @click returns event
• @double-click returns event
• @right-click returns event
• @mouseover returns event
• @mouseout returns event

Once the map is loaded, it $emit's itself (map instance) via the event mounted (thanks thefoxie).

The default template for the slot also has a slot prop of map which can be referred to.

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

Marker

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
• @double-click returns event
• @right-click returns event
• @positionChanged (depreciated) returns new position

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

InfoWindow

InfoWindows are placed with Maps can take a few options using the type google.maps.InfoWindowOptions. A position option { lat: number, lng: number } (Type: google.maps.LatLngLiteral) 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>

Popup

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:

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>

Heatmap

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.

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

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
• @double-click returns PolyMouseEvent
• @drag returns MouseEvent
• @drag-end returns MouseEvent
• @drag-start returns MouseEvent
• @mouseover returns PolyMouseEvent
• @right-click returns PolyMouseEvent
• @path-changed returns array of points

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

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:

• @bounds-changed (Only rectangles) returns new bounds
• @center-changed (Only circles) returns new center
• @radius-changed (Only circles) returns new radius
• @click returns PolyMouseEvent
• @double-click returns PolyMouseEvent
• @drag returns MouseEvent
• @drag-end returns MouseEvent
• @drag-start returns MouseEvent
• @mouseover returns PolyMouseEvent
• @right-click returns PolyMouseEvent

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

Data / GeoJSON

GeoJSON is an open standard format designed for representing simple geographical features, along with their non-spatial attributes. It can be used in Google Maps, and now in this libary using two new components: GmapsData, and GmapsDataGeoJson.

Because of how Google implements this feature, this library limits you to only one GmapsData element per map. That element will take any global styles and emit all the event listeners. The GmapsDataGeoJson is the element where actual GeoJSON data can be added, along with any overriding styles.

The full Google Maps API for Data has not been incorporated (no drawing yet), but it's certainly able to display any GeoJSON you have.

GmapsData supports the following events: @click, contextmenu, @dblclick, mousedown, mouseout, mouseover, mouseup, rightclick (which are most of those available)

Each returns Google's google.maps.data.MouseEvent which includes the feature hit and latLng.

GmapsData presently only takes an options prop which is of type google.maps.data.StyleOptions. This will effectively be the default style for all Features imported into the data. To override this, you need to set the options for the individual Feature in the GmapsDataGeoJson component.

GmapsDataGeoJson does not have events (all events are emited together from the GmapsData if you include it).

GmapsData also only takes an options prop which is of type google.maps.data.StyleOptions. This is the override style for the Feature(s) defined in this component..

<template>
  <gmaps-map>
    <gmaps-data>
      <gmaps-data-geo-json :geo-json="geoJson" />
      <gmaps-data-geo-json :geo-json="geoJson2" :options="geoJson2Style" />
    </gmaps-data>
  </gmaps-map>
</template>

<script>
  import { gmapsMap, gmapsData, gmapsDataGeoJson } from 'x5-gmaps';

  import geoJson from '../../../public/data/geoJsonData.json';
  import geoJsonL from '../../../public/data/geoJsonDataL.json';

  export default {
    name: 'ExampleGeoJson',
    components: { gmapsMap, gmapsData, gmapsDataGeoJson },
    data: () => ({
      geoJson,
      geoJsonL,
      geoJsonLStyle: { fillColor: 'black' }
    })
  };
</script>

Accessing the Google Maps API

While this should rarely be needed, if you need to access the Google Maps API, you must wait for it to be inserted and loaded. A promised is provided which should return that API when it's ready by importing gmaps (e.g. import { gmaps } from 'x5-gmaps'). Usually it should already be loaded and available via window.google.maps.

The return of this promise is the maps object of the google object most of Google's examples use.

// Example
import { gmaps } from 'x5-gmaps';

export default {
  data: () => ({
    GooglePlacesService: null
  }),
  mounted() {
    gmaps().then(maps => {
      PlacesService = new maps.places.AutocompleteService();
    });
  }
};

Google Places Library

As mentioned above, additional libraries can be used in conjunction with this package, and as an example, this is how you would include the Places Library.

// main.js
Vue.use(x5GMaps, { key: 'YOUR_GOOGLE_KEY', libraries: ['places'] });

⚠️ It's highly recommended to check out the demo at the top of this readme to have a play around.

Custom map slots

While you shouldn't see these for too long while the map loads (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>

Authors

• Keagan Chisnall

License

This project is licensed under the MIT License - see the LICENSE.md file for details