Skip to content

README.md

Latest commit

 

History

History
106 lines (75 loc) · 3.97 KB

README.md

File metadata and controls

106 lines (75 loc) · 3.97 KB

location-picker

CI npm version npm downloads License: MIT

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