https://github.com/cyphercodes/location-picker
An open source location picker plugin using Google Maps v3 that works with all JavaScript flavors!
https://github.com/cyphercodes/location-picker
google-maps javascript javascript-plugin locationpicker typescript
Last synced: 11 days ago
JSON representation
An open source location picker plugin using Google Maps v3 that works with all JavaScript flavors!
- Host: GitHub
- URL: https://github.com/cyphercodes/location-picker
- Owner: cyphercodes
- License: gpl-3.0
- Created: 2018-02-26T16:44:01.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-07-06T09:14:48.000Z (almost 2 years ago)
- Last Synced: 2025-11-02T07:18:31.220Z (6 months ago)
- Topics: google-maps, javascript, javascript-plugin, locationpicker, typescript
- Language: TypeScript
- Homepage: https://cyphercodes.github.io/location-picker/
- Size: 420 KB
- Stars: 77
- Watchers: 4
- Forks: 15
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: code-of-conduct.md
Awesome Lists containing this project
- stars - cyphercodes/location-picker - An open source location picker plugin using Google Maps v3 that works with all JavaScript flavors! (TypeScript)
README
# location-picker
[](https://github.com/cyphercodes/location-picker/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/location-picker)
[](https://www.npmjs.com/package/location-picker)
[](https://opensource.org/licenses/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](#migration-from-v1) section below.
---
## Install
```bash
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)
```ts
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
```js
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:
```ts
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
```ts
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`. 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
```bash
npm install
npm run lint
npm run typecheck
npm run test
npm run build
```
## License
MIT