gmap-vue

library3.5.4jsnpmunverified

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.

web-framework

npm install gmap-vue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GMAP-VUE

gmap-vue

web-frameworkjavascriptv3.5.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GmapVue (plugin)

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

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

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

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

✗ import { gmapApi } 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

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

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

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.

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

Debug

Known issues

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

affects: >=3.0.0

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

affects: >=2.0.0 <3.0.0

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

affects: >=2.0.0

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

affects: all

Errors

Common errors & fixes

ReferenceError: GmapMap is not defined

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.

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.

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)

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.

Upgrade

Version history

3.5.4latest on npm

Audit

Dependencies

vuerequiredPeer dependency for Vue 2 compatibility, required for the plugin to function.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/diegoazh/gmap-vue ↗

packagehttps://www.npmjs.com/package/gmap-vue ↗

homepagehttps://gmap-vue.netlify.app ↗