{"id":10957,"library":"gmap-vue","title":"GmapVue - Google Maps for Vue 2","description":"GmapVue is an actively maintained Google Maps component library specifically designed for Vue 2 applications, currently at version 3.5.4. It originated as a fork of the popular but unmaintained `vue2-google-maps` project, ensuring continued support and development for Vue 2 users. The library provides a suite of components for integrating various Google Maps features, including maps, markers, polygons, and autocomplete functionalities, all within a declarative Vue syntax. Recent releases, labeled `gmv3_vX.Y.Z` in its internal changelog, indicate ongoing bug fixes and feature enhancements, with multiple updates in 2024 and 2025. Its key differentiator is its dedicated focus on Vue 2 compatibility and active maintenance, filling a gap left by its predecessor, and offering a robust solution for developers needing Google Maps in their Vue 2 projects.","status":"active","version":"3.5.4","language":"javascript","source_language":"en","source_url":"https://github.com/diegoazh/gmap-vue","tags":["javascript"],"install":[{"cmd":"npm install gmap-vue","lang":"bash","label":"npm"},{"cmd":"yarn add gmap-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add gmap-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue 2 compatibility, required for the plugin to function.","package":"vue","optional":false}],"imports":[{"note":"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.","wrong":"const GmapVue = require('gmap-vue');\n// Before v2.0.0: import * as GmapVue from 'gmap-vue';","symbol":"GmapVue (plugin)","correct":"import Vue from 'vue';\nimport GmapVue from 'gmap-vue';\n\nVue.use(GmapVue, {\n  load: { key: process.env.VUE_APP_GOOGLE_MAPS_API_KEY ?? '', libraries: 'places' },\n});"},{"note":"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.","wrong":"import { gmapApi } from 'gmap-vue/helpers';","symbol":"getGoogleMapsAPI","correct":"import { getGoogleMapsAPI } from 'gmap-vue/helpers';"},{"note":"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.","wrong":"import { MapElementMixin } from 'gmap-vue/helpers';","symbol":"MapElementMixin","correct":"import { MapElementMixin } from 'gmap-vue/components';"}],"quickstart":{"code":"import Vue from 'vue';\nimport GmapVue from 'gmap-vue';\n\n// Replace 'YOUR_GOOGLE_MAPS_API_KEY' with your actual API key\nVue.use(GmapVue, {\n  load: {\n    key: process.env.VUE_APP_GOOGLE_MAPS_API_KEY ?? 'YOUR_GOOGLE_MAPS_API_KEY',\n    libraries: 'places' // Optional: Load additional libraries like 'places' for autocomplete\n  },\n  installComponents: true, // This is true by default, explicitly stating for clarity\n});\n\nnew Vue({\n  el: '#app',\n  template: `\n    <div style=\"width: 100%; height: 500px;\">\n      <GmapMap\n        :center=\"{lat: -34.397, lng: 150.644}\"\n        :zoom=\"12\"\n        map-type-id=\"terrain\"\n        style=\"width: 100%; height: 100%\"\n      >\n        <GmapMarker\n          :position=\"markerPosition\"\n          :clickable=\"true\"\n          :draggable=\"true\"\n          @click=\"center = markerPosition\"\n          @dragend=\"updateMarkerPosition\"\n        />\n      </GmapMap>\n    </div>\n  `,\n  data() {\n    return {\n      center: {lat: -34.397, lng: 150.644},\n      markerPosition: {lat: -34.397, lng: 150.644}\n    }\n  },\n  methods: {\n    updateMarkerPosition(event) {\n      this.markerPosition = {\n        lat: event.latLng.lat(),\n        lng: event.latLng.lng()\n      };\n    }\n  }\n});","lang":"javascript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Refactor your `autocomplete` component usage to render the input element within its `default` slot instead of the `input` named slot.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The GmapVue plugin has not been properly installed or registered with your Vue instance, meaning its components are not globally available.","error":"ReferenceError: GmapMap is not defined"},{"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.","cause":"The `key` property within the GmapVue plugin's `load` options is either absent, empty, or contains an invalid Google Maps API key.","error":"Error: Google Maps API key is missing or invalid. Please check your `load.key` configuration."},{"fix":"Update all calls to `gmapApi` to `getGoogleMapsAPI` and ensure it is correctly imported from `'gmap-vue/helpers'` as a named export.","cause":"Attempting to use the deprecated `gmapApi` helper function after upgrading to v3.0.0 or a later version.","error":"Vue warn: Property or method \"gmapApi\" is not defined on the instance but referenced during render."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'lat') (or similar when interacting with map objects)"}],"ecosystem":"npm"}