GmapVue - Google Maps for Vue 2

Common errors

• ReferenceError: GmapMap is not defined

  cause The GmapVue plugin has not been properly installed or registered with your Vue instance, meaning its components are not globally available.
  fix Ensure you have called `Vue.use(GmapVue, { load: { key: 'YOUR_API_KEY' } });` in your main JavaScript file (e.g., `main.js` or `app.js`) before your root Vue app instance is created.

• Error: Google Maps API key is missing or invalid. Please check your `load.key` configuration.

  cause The `key` property within the GmapVue plugin's `load` options is either absent, empty, or contains an invalid Google Maps API key.
  fix Provide a valid Google Maps API key as a string to the `load.key` option when initializing the plugin: `Vue.use(GmapVue, { load: { key: 'YOUR_VALID_API_KEY' } })`. Confirm the key is enabled for the Google Maps JavaScript API in your Google Cloud Console.

• Vue warn: Property or method "gmapApi" is not defined on the instance but referenced during render.

  cause Attempting to use the deprecated `gmapApi` helper function after upgrading to v3.0.0 or a later version.
  fix Update all calls to `gmapApi` to `getGoogleMapsAPI` and ensure it is correctly imported from `'gmap-vue/helpers'` as a named export.

• TypeError: Cannot read properties of undefined (reading 'lat') (or similar when interacting with map objects)

  cause Attempting to access properties or methods of Google Maps API objects (e.g., `Map`, `Marker`) before the API has fully loaded or before the component has rendered and initialized the underlying map instance.
  fix Ensure that the Google Maps API is fully loaded before interacting with its objects. Use `v-if` or `v-show` directives on your map components, or react to events like `@idle` or `@loaded` emitted by `GmapMap` to ensure readiness.

Warnings

• breaking In v3.0.0, several core configuration options and helper functions were renamed. `autobindAllEvents` became `autoBindAllEvents`, `vueGoogleMapsInit` was renamed to `GoogleMapsCallback`, and `gmapApi` became `getGoogleMapsAPI`. The `MapElementMixin`'s import path also changed.
  Fix: Update your plugin configuration and imports to use the new names: `autoBindAllEvents`, `GoogleMapsCallback`, `getGoogleMapsAPI`, and adjust the import path for `MapElementMixin` to `gmap-vue/components`.
• breaking Version 2.0.0 introduced a significant refactor. All components were rewritten in SFCs, the `MarkerCluster` component was renamed to `Cluster`, and the underlying clustering library changed from `@google/markerclustererplus` to `@googlemaps/markerclusterer`. The package's default export also changed, now directly exporting the install function.
  Fix: For upgrades from pre-v2.0.0, refactor `MarkerCluster` usage to `Cluster` and ensure correct clustering library dependencies. Update plugin import statements from `import * as GmapVue` to `import GmapVue`.
• breaking The `autocomplete` component's slot for the input element was changed in v2.0.0. It now expects the `default` slot instead of the previously named `input` slot. While the `input` slot might have worked in v1.5.0, it is deprecated and may not function correctly in later versions.
  Fix: Refactor your `autocomplete` component usage to render the input element within its `default` slot instead of the `input` named slot.
• gotcha When consuming GmapVue via a CDN or manually including the `dist/gmap-vue.js` file, component names and attributes must be written in kebab-case (e.g., `<gmap-map>`) in your HTML templates, diverging from the PascalCase (e.g., `<GmapMap>`) typically used with npm installations and Vue SFCs.
  Fix: Standardize your component casing based on your installation method. For CDN/manual inclusion, use kebab-case. For npm installations within Vue CLI or webpack-based projects using SFCs, PascalCase is the standard after global plugin registration.

Install

• npm install gmap-vue npm
• yarn add gmap-vue yarn
• pnpm add gmap-vue pnpm

Imports

• GmapVue (plugin)
  wrong:

  const GmapVue = require('gmap-vue');
  // Before v2.0.0: import * as GmapVue from 'gmap-vue';

  correct:

  import Vue from 'vue';
  import GmapVue from 'gmap-vue';
  
  Vue.use(GmapVue, {
    load: { key: process.env.VUE_APP_GOOGLE_MAPS_API_KEY ?? '', libraries: 'places' },
  });

  Since v2.0.0, the plugin is imported as a default export. After `Vue.use()`, components like `GmapMap` and `GmapMarker` become globally available in your Vue templates. Ensure your Google Maps API key is provided during initialization.
• getGoogleMapsAPI
  wrong:

  import { gmapApi } from 'gmap-vue/helpers';

  correct:

  import { getGoogleMapsAPI } from 'gmap-vue/helpers';

  The helper function `gmapApi` was renamed to `getGoogleMapsAPI` in v3.0.0. This function allows you to access the Google Maps API object after it has fully loaded.
• MapElementMixin
  wrong:

  import { MapElementMixin } from 'gmap-vue/helpers';

  correct:

  import { MapElementMixin } from 'gmap-vue/components';

  In v3.0.0, the `MapElementMixin` was moved from the `helpers` export object to the `components` export object, requiring an update to its import path.

Quickstart

This example demonstrates how to install GmapVue as a Vue plugin, initialize it with a Google Maps API key, and render a basic map with a draggable marker. The marker's position updates on drag.

import Vue from 'vue';
import GmapVue from 'gmap-vue';

// Replace 'YOUR_GOOGLE_MAPS_API_KEY' with your actual API key
Vue.use(GmapVue, {
  load: {
    key: process.env.VUE_APP_GOOGLE_MAPS_API_KEY ?? 'YOUR_GOOGLE_MAPS_API_KEY',
    libraries: 'places' // Optional: Load additional libraries like 'places' for autocomplete
  },
  installComponents: true, // This is true by default, explicitly stating for clarity
});

new Vue({
  el: '#app',
  template: `
    <div style="width: 100%; height: 500px;">
      <GmapMap
        :center="{lat: -34.397, lng: 150.644}"
        :zoom="12"
        map-type-id="terrain"
        style="width: 100%; height: 100%"
      >
        <GmapMarker
          :position="markerPosition"
          :clickable="true"
          :draggable="true"
          @click="center = markerPosition"
          @dragend="updateMarkerPosition"
        />
      </GmapMap>
    </div>
  `,
  data() {
    return {
      center: {lat: -34.397, lng: 150.644},
      markerPosition: {lat: -34.397, lng: 150.644}
    }
  },
  methods: {
    updateMarkerPosition(event) {
      this.markerPosition = {
        lat: event.latLng.lat(),
        lng: event.latLng.lng()
      };
    }
  }
});