google-map-ts-vue3

A Vue 3 component for integrating Google Maps with full TypeScript support.

This library provides a declarative interface for rendering Google Maps with markers, polylines, polygons, circles, and rectangles, utilizing the latest Google Maps JavaScript API features including Advanced Markers.

Installation

npm install google-map-ts-vue3

google-map-ts-vue3 v2 is an ESM-only package. Use import syntax; on CommonJS, Node.js ^20.19.0 || >=22.12.0 can load it via require() (require(esm) is unflagged on those releases).

Usage

Basic Example

<script setup lang="ts">
import { GoogleMap } from 'google-map-ts-vue3'
</script>

<template>
  <GoogleMap
    apiKey="YOUR_GOOGLE_MAPS_API_KEY"
    :options="{
      center: { lat: 35.1, lng: 135.1 },
      zoom: 5,
      mapId: 'DEMO_MAP_ID'
    }"
  />
</template>

Complete Example with Overlays

<script setup lang="ts">
import { GoogleMap } from 'google-map-ts-vue3'
</script>

<template>
  <GoogleMap
    apiKey="YOUR_GOOGLE_MAPS_API_KEY"
    :options="{
      center: { lat: 35.1, lng: 135.1 },
      zoom: 5,
      mapId: 'DEMO_MAP_ID'
    }"
    :markers="[
      {
        position: { lat: 35.1, lng: 135.1 },
        title: 'Location 1'
      },
      {
        position: { lat: 37.1, lng: 139.1 },
        title: 'Location 2'
      }
    ]"
    :polylines="[
      {
        path: [
          { lat: 35.1, lng: 135.1 },
          { lat: 37.1, lng: 139.1 }
        ],
        geodesic: true,
        strokeColor: '#ff0000',
        strokeOpacity: 1.0,
        strokeWeight: 2
      }
    ]"
    :polygons="[
      {
        paths: [
          { lat: 30, lng: 140 },
          { lat: 31, lng: 141 },
          { lat: 30, lng: 145 },
          { lat: 33, lng: 140 }
        ],
        strokeColor: '#ff0000',
        strokeOpacity: 0.8,
        strokeWeight: 3,
        fillColor: '#ff0000',
        fillOpacity: 0.35
      }
    ]"
    :circles="[
      {
        center: { lat: 39.1, lng: 140.1 },
        radius: 100000,
        strokeColor: '#ff0000',
        strokeOpacity: 0.8,
        strokeWeight: 2,
        fillColor: '#ff0000',
        fillOpacity: 0.35
      }
    ]"
    :rectangles="[
      {
        bounds: {
          north: 30,
          south: 33,
          east: 133,
          west: 130
        },
        strokeColor: '#ff0000',
        strokeOpacity: 0.8,
        strokeWeight: 2,
        fillColor: '#ff0000',
        fillOpacity: 0.35
      }
    ]"
  />
</template>

API Reference

Props

Property	Type	Required	Default	Description
apiKey	string	Yes	-	Google Maps API key. Obtain from Google Cloud Console
options	google.maps.MapOptions	Yes	-	Map configuration options. See MapOptions
markers	google.maps.marker.AdvancedMarkerElementOptions[]	No	[]	Array of advanced marker configurations. See AdvancedMarkerElementOptions
polylines	google.maps.PolylineOptions[]	No	[]	Array of polyline configurations. See PolylineOptions
polygons	google.maps.PolygonOptions[]	No	[]	Array of polygon configurations. See PolygonOptions
circles	google.maps.CircleOptions[]	No	[]	Array of circle configurations. See CircleOptions
rectangles	google.maps.RectangleOptions[]	No	[]	Array of rectangle configurations. See RectangleOptions
height	string	No	"500px"	Height of the map container
width	string	No	"500px"	Width of the map container
libraries	string	No	"marker,geometry,drawing,places"	Comma-separated list of Google Maps libraries to load. See Libraries
scriptLoadingTimeout	number	No	5000	Timeout in milliseconds for loading the Google Maps JavaScript API

Events

The component emits the following events when Google Maps objects are created, providing access to the underlying API instances:

Event	Payload Type	Description
map-created	google.maps.Map	Emitted when the map instance is created
markers-created	google.maps.marker.AdvancedMarkerElement[]	Emitted when marker instances are created
polylines-created	google.maps.Polyline[]	Emitted when polyline instances are created
polygons-created	google.maps.Polygon[]	Emitted when polygon instances are created
circles-created	google.maps.Circle[]	Emitted when circle instances are created
rectangles-created	google.maps.Rectangle[]	Emitted when rectangle instances are created

Event Usage Example

<script setup lang="ts">
import { GoogleMap } from 'google-map-ts-vue3'

const handleMapCreated = (map: google.maps.Map) => {
  console.log('Map instance:', map)
}

const handleMarkersCreated = (markers: google.maps.marker.AdvancedMarkerElement[]) => {
  console.log('Marker instances:', markers)
}
</script>

<template>
  <GoogleMap
    apiKey="YOUR_GOOGLE_MAPS_API_KEY"
    :options="{ center: { lat: 35.1, lng: 135.1 }, zoom: 5, mapId: 'DEMO_MAP_ID' }"
    :markers="[{ position: { lat: 35.1, lng: 135.1 }, title: 'Marker' }]"
    @map-created="handleMapCreated"
    @markers-created="handleMarkersCreated"
  />
</template>

Important Notes

Map ID Requirement

The mapId property is required in options when using Advanced Markers (the default marker type). Create a Map ID in the Google Cloud Console.

TypeScript Support

This library includes full TypeScript type definitions from @types/google.maps, providing comprehensive type safety and IDE autocomplete for all Google Maps API features.

License

This project is licensed under the MIT License - see the LICENSE file for details.