location-picker

An open source location picker plugin using Google Maps v3, written in modern TypeScript, shipped as both ESM and CJS with full type definitions.

v2 is a modernization release. See the Migration from v1 section below.

---

Install

npm install location-picker

You also need the Google Maps JavaScript API loaded on your page (either via the classic script tag or the official @googlemaps/js-api-loader).

Usage

ESM (bundlers / modern browsers)

import { LocationPicker } from 'location-picker';
import 'location-picker/style.css';

const lp = new LocationPicker(
  'map',
  { setCurrentPosition: true, onLocationChange: (p) => console.log(p) },
  { zoom: 15 },
);

CommonJS

const { LocationPicker } = require('location-picker');
require('location-picker/style.css');

const lp = new LocationPicker('map');

AdvancedMarkerElement

If you load the Google Maps marker library, set useAdvancedMarker: true and the picker will use google.maps.marker.AdvancedMarkerElement instead of the CSS-pin overlay:

const lp = new LocationPicker('map', { useAdvancedMarker: true }, { mapId: 'YOUR_MAP_ID' });

API

new LocationPicker(element, options?, mapOptions?)

• element: string | HTMLElement - element id or DOM node.
• options: LocationPickerOptions:
  • setCurrentPosition?: boolean - default true. Skipped if lat/lng provided.
  • lat?: number, lng?: number - initial center.
  • useAdvancedMarker?: boolean - default false.
  • onLocationChange?: (pos: LatLng) => void - called on each idle event.
• mapOptions: google.maps.MapOptions - forwarded to new google.maps.Map.

Methods

• getMarkerPosition(): { lat: number; lng: number }
• setLocation(lat: number, lng: number): void
• setCurrentPosition(): Promise<{ lat: number; lng: number }> - breaking in v2, now returns a Promise.
• destroy(): void - removes listeners and the marker DOM.

Types

import type { LatLng, LocationPickerOptions } from 'location-picker';

Migration from v1

v1	v2
import LocationPicker from 'location-picker'	Still works. Also: import { LocationPicker } from 'location-picker'.
setCurrentPosition() returned void	Returns Promise<LatLng>. Rejects on failure instead of console.log.
UMD / minified UMD bundle	Removed. Use ESM (dist/index.mjs) or CJS (dist/index.cjs).
@types/googlemaps	Replaced by @types/google.maps.
CSS was bundled automatically	Now opt-in: import 'location-picker/style.css'.
No destroy()	destroy() available for cleanup (SPAs, HMR).
No idle callback	onLocationChange option.
No AdvancedMarker	useAdvancedMarker: true opts into AdvancedMarkerElement.

Node >=18 is required to build/develop the library. Consumers are unaffected.

Development

npm install
npm run lint
npm run typecheck
npm run test
npm run build

License

MIT