What is this?

A single Custom Element that wraps the Google Maps JavaScript API. No boilerplate. No framework lock-in. Just drop a tag and go.

<google-map zoom="12" center="35.658584,139.7454316" theme="dark"></google-map>

That's a fully interactive dark-themed map. Really.

Highlights

| | | |---|---| | One tag, full map | Works out of the box — zero config needed | | 6 built-in themes | standard, silver, retro, dark, night, aubergine | | Markers that pop | Circles, images, and rich HTML balloons | | Geocoding baked in | Address ↔ coordinates in a single call | | Distance math | Meters between any two points on Earth |

Getting Started

Install

npm install google-map-extension

Minimal Setup

<google-map
  zoom="12"
  center="35.658584,139.7454316"
  type="roadmap"
  theme="dark"
  zoom-control
  streetview-control
  fullscreen-control
  theme-control></google-map>

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
<script type="module">
  import 'google-map-extension';
</script>

That's it. You have a dark-themed, fully interactive map with controls.

Usage

React to clicks

const map = document.querySelector('#map');

map.on('click.map', event => {
  const position = event.detail;
  map.moveToPosition(position);
});

Drop a circle marker

const marker = await map.addMarker({
  color: 'rgb(0,122,255)',
  size: 60,
  position: { lat: 35.650584, lng: 139.7454316 }
});

Use your own image

const marker = await map.addMarker({
  image: 'avatar.png',
  color: 'rgb(0,122,255)',
  size: 60,
  position: { lat: 35.650584, lng: 139.7454316 }
});

Attach a balloon

const marker = await map.addMarker({
  position: { lat: 35.650584, lng: 139.7454316 },
  info: '<strong>Hello!</strong>'
});

Move & remove

marker.moveToPosition({ lat: 35.660584, lng: 139.7554316 });

map.removeMarker(marker);

Geocoding & distance

import { GoogleMapUtils } from 'google-map-extension';

// Address -> coordinates
const latlng = await GoogleMapUtils.getLatLngFromAddress('Tokyo Tower, Japan');
// => { lat: 35.6585..., lng: 139.7454... }

// Coordinates -> address
const address = await GoogleMapUtils.getAddressFromLatLng({ lat: 35.6585, lng: 139.7454 });

// Distance in meters (requires libraries=geometry)
const meters = GoogleMapUtils.computeDistanceBetween(
  { lat: 35.6581, lng: 139.7414 },
  { lat: 35.6706, lng: 139.7672 }
);

API Reference

<google-map> Element

Attributes

| Attribute | Type | Default | Description | |---|---|---|---| | zoom | number | 13 | Zoom level, 1 (world) – 21 (building) | | center | string | "0,0" | Starting position — "lat,lng" | | type | string | "roadmap" | roadmap / satellite / hybrid / terrain | | theme | string | "standard" | standard / silver / retro / dark / night / aubergine | | zoom-control | boolean | — | Show zoom buttons | | streetview-control | boolean | — | Show Street View pegman | | fullscreen-control | boolean | — | Show fullscreen toggle | | theme-control | boolean | — | Show theme picker |

Zoom level previews

Map type previews

| Type | What you get | Preview | |---|---|---| | roadmap | Classic road map | | | satellite | Google Earth imagery | | | hybrid | Satellite + road labels | | | terrain | Elevation & terrain | |

Theme previews

| Theme | Preview | |---|---| | standard | | | silver | | | retro | | | dark | | | night | | | aubergine | |

Events

click.map

Fires on map click. The tapped coordinates come through event.detail.

map.on('click.map', event => {
  const position = event.detail; // { lat, lng }
});

Properties

| Property | Type | Description | |---|---|---| | map | google.maps.Map | Raw Maps JavaScript API instance — full power when you need it |

Methods

addMarker(option?)

Drop a marker on the map.

map.addMarker(option?: {
  position?: { lat: number, lng: number },
  size?: number,
  visible?: boolean,
  image?: string,
  color?: string,
  info?: string
}): Promise<GoogleMapCircleMarker>

| Parameter | Type | Default | Description | |---|---|---|---| | position | { lat, lng } | Map center | Where to place the marker | | size | number | 50 | Diameter in pixels | | visible | boolean | true | Show on creation | | image | string | — | Image URL inside the marker | | color | string | "rgb(0,122,255)" | Fill color | | info | string | — | Balloon content (HTML ok) |

Returns Promise<GoogleMapCircleMarker>

removeMarker(marker)

Remove a marker from the map.

map.removeMarker(marker: GoogleMapCircleMarker): GoogleMap

moveToPosition(latlng, zoomToCurrentPosition?)

Pan the map to a new location.

map.moveToPosition(
  latlng: google.maps.LatLng | google.maps.LatLngLiteral,
  zoomToCurrentPosition?: boolean  // default: true
): GoogleMap

zoomToFitAllPositions(positions)

Auto-zoom to fit every marker or coordinate in view.

map.zoomToFitAllPositions(
  positions: google.maps.LatLng[] |
             google.maps.LatLngLiteral[] |
             google.maps.Marker[] |
             GoogleMapCircleMarker[]
): GoogleMap

GoogleMapCircleMarker

The marker object returned by addMarker().

Methods

moveToPosition(latlng, zoomToCurrentPosition?)

Slide the marker to a new spot.

marker.moveToPosition(
  latlng: google.maps.LatLng | google.maps.LatLngLiteral,
  zoomToCurrentPosition?: boolean  // default: true
): GoogleMapCircleMarker

getPosition()

Get the marker's current coordinates.

marker.getPosition(): google.maps.LatLngLiteral

setVisible(visible)

Show or hide the marker.

marker.setVisible(visible: boolean): GoogleMapCircleMarker

setInfo(content)

Set the balloon content. HTML is supported.

marker.setInfo(content: string): GoogleMapCircleMarker

clearInfo()

Dismiss the balloon.

marker.clearInfo(): GoogleMapCircleMarker

GoogleMapUtils

Standalone helpers — no map instance required.

import { GoogleMapUtils } from 'google-map-extension';

Methods

getCurrentPosition(option?)

Grab the device's current location.

GoogleMapUtils.getCurrentPosition(option?: {
  timeout?: number,    // ms, default: 5000
  maximumAge?: number  // ms, default: 0
}): Promise<google.maps.LatLngLiteral>

getLatLngFromAddress(address)

Turn an address into coordinates.

GoogleMapUtils.getLatLngFromAddress(address: string): Promise<google.maps.LatLngLiteral>

getAddressFromLatLng(latlng)

Turn coordinates into an address.

GoogleMapUtils.getAddressFromLatLng(
  latlng: google.maps.LatLng | google.maps.LatLngLiteral
): Promise<string | undefined>

computeDistanceBetween(from, to)

Meters between two points on the globe.

Requires libraries=geometry in your API script tag.

GoogleMapUtils.computeDistanceBetween(
  from: google.maps.LatLng | google.maps.LatLngLiteral,
  to: google.maps.LatLng | google.maps.LatLngLiteral
): number

Examples

Working demos are in the examples/ directory.

License

MIT