GmapVue for Vue 3

Use @gmap-vue/v3 for new Vue applications. The Vue 3 package is the primary path for current development; Vue 2 documentation remains available for legacy applications.

Quick path

1. Install the package.
2. Import the exported stylesheet.
3. Install the plugin with a browser-restricted Google Maps JavaScript API key.

NPM

npm install @gmap-vue/v3 --save

Yarn

yarn add @gmap-vue/v3

PNPM

pnpm add @gmap-vue/v3

main.ts

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

const app = createApp(App);

app.use(
  createGmapVuePlugin({
    load: {
      key: import.meta.env.VITE_GOOGLE_MAPS_API_KEY,
    },
  }),
);

app.mount("#app");

API key safety

Google Maps JavaScript API keys used in browser apps are public identifiers. Do not treat a Vite VITE_* value as a server secret; it is bundled into client-side code.

Before shipping, make sure you:

• restrict the key by HTTP referrer in Google Cloud Console;
• enable only the Google Maps APIs your app needs;
• avoid committing unrestricted keys or screenshots containing real keys;
• rotate the key if it was exposed without restrictions.

Supported imports

Use only the documented package entrypoints:

Purpose	Import
Plugin factory and utilities	@gmap-vue/v3
Components	@gmap-vue/v3/components
Composables	@gmap-vue/v3/composables
Injection keys	@gmap-vue/v3/keys
Interfaces	@gmap-vue/v3/interfaces
Types	@gmap-vue/v3/types
Styles	@gmap-vue/v3/dist/style.css

Deep imports into src/ or internal files are unsupported and can break between releases.

CDN usage

Bundlers are recommended. If you need a CDN, load the package as an ES module and keep component names kebab-case in in-browser templates. The published ES module keeps Vue and other externals external, so browser-only CDN usage may require an import map or CDN endpoint that rewrites external dependencies.

jsdelivr

<script type="module">
  import {createGmapVuePlugin} from
  'https://cdn.jsdelivr.net/npm/@gmap-vue/v3/dist/main.es.js';
</script>

unpkg

<script type="module">
  import {createGmapVuePlugin} from
  'https://unpkg.com/@gmap-vue/v3/dist/main.es.js';
</script>

warning

In browser templates, use kebab-case component and attribute names. For example, write <gmv-map> instead of <GmvMap>.

Dynamic library import

GmapVue follows the Google Maps team recommendation to use dynamic library loading. For more information, see the Google Maps JavaScript API dynamic library import documentation.

Migrating from the Vue 2 package

• Import from @gmap-vue/v3 instead of gmap-vue.

• Install with the named createGmapVuePlugin factory:

  import { createGmapVuePlugin } from "@gmap-vue/v3";

• Components are lazy-loaded and prefixed with Gmv, for example GmvMap.

• installComponents was removed because components are registered by the Vue 3 plugin.

• $gmapOptions exposes the final plugin options object.

• Mixins were replaced by composables.

• MapElementFactory is now pluginComponentBuilder under utilities.

• Old helpers and factories that are not exported from documented entrypoints are internal.

note

If your app is still on Vue 2, keep using the Vue 2 legacy docs. New applications should start with Vue 3.