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