@gmap-vue/v3

Vue 3 components and composables for the Google Maps JavaScript API.

@gmap-vue/v3 is the actively developed GmapVue package. It provides Vue wrappers for maps, markers, info windows, shapes, clusters, layers, autocomplete, and Street View, plus composables for accessing the underlying Google Maps instances.

Documentation

• Vue 3 guide
• Component API reference
• Composables API

Installation

npm install @gmap-vue/v3

pnpm add @gmap-vue/v3

yarn add @gmap-vue/v3

Quick start

Register the plugin once in your Vue app:

import { createApp } from 'vue';
import { createGmapVuePlugin } from '@gmap-vue/v3';
import '@gmap-vue/v3/dist/style.css';
import App from './App.vue';

createApp(App)
  .use(
    createGmapVuePlugin({
      load: {
        key: import.meta.env.VITE_GOOGLE_MAPS_API_KEY,
      },
    }),
  )
  .mount('#app');

Then use the public components in your templates:

<template>
  <GmvMap
    :center="{ lat: -34.6037, lng: -58.3816 }"
    :zoom="12"
    style="width: 100%; height: 500px"
  >
    <GmvMarker :position="{ lat: -34.6037, lng: -58.3816 }" />
  </GmvMap>
</template>

Google Maps API key

You need a browser API key for the Google Maps JavaScript API. For production applications:

• restrict the key by HTTP referrer,
• enable only the APIs and libraries your app uses,
• monitor billing and quota in Google Cloud Console,
• avoid calling paid APIs from high-frequency map events.

Public entrypoints

Use the package entrypoints instead of deep imports:

import { createGmapVuePlugin, GmvMap } from '@gmap-vue/v3';
import { useMapPromise } from '@gmap-vue/v3/composables';
import { mapPromiseKey } from '@gmap-vue/v3/keys';
import type { IMapLayerVueComponentExpose } from '@gmap-vue/v3/interfaces';

Migrating from Vue 2

The Vue 3 package changes the plugin structure, component names, and instance-access patterns. See the Vue 3 migration guide before migrating from the legacy gmap-vue package.

Contributing

Contributions are welcome. Please read the repository-level README.md, AGENTS.md, and Copilot instructions before opening a PR.