跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

location-picker

Add a map location picker to a web form or web app with the location-picker npm package (the <location-picker> web component and the LocationPicker JavaScript class). Use it when a user must choose one precise latitude/longitude point on a map, such as a store, branch or sensor location, a delivery or pickup pin, an event venue, the place of a report or a home address, and the point must be submitted with a form, bound in React, Vue, Angular, Svelte, Solid or Preact, or written into hidden lat/lng inputs (Laravel, Django, Rails, jQuery, Livewire, Alpine, htmx). Covers the keyless OpenStreetMap default, Google Maps and MapLibre providers, address search, reverse geocoding, a locate-me button, parsing coordinates from text or map URLs, Content Security Policy, SSR and hydration, a phone-first field mode, the hosted pick link that asks a person for a location by URL, and upgrading location-picker 1.x or 2.x code (global locationPicker, getMarkerPosition, setCurrentPosition).

cyphercodes · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add cyphercodes/location-picker --skill location-picker

技能说明


name: location-picker description: >- Add a map location picker to a web form or web app with the location-picker npm package (the web component and the LocationPicker JavaScript class). Use it when a user must choose one precise latitude/longitude point on a map, such as a store, branch or sensor location, a delivery or pickup pin, an event venue, the place of a report or a home address, and the point must be submitted with a form, bound in React, Vue, Angular, Svelte, Solid or Preact, or written into hidden lat/lng inputs (Laravel, Django, Rails, jQuery, Livewire, Alpine, htmx). Covers the keyless OpenStreetMap default, Google Maps and MapLibre providers, address search, reverse geocoding, a locate-me button, parsing coordinates from text or map URLs, Content Security Policy, SSR and hydration, a phone-first field mode, the hosted pick link that asks a person for a location by URL, and upgrading location-picker 1.x or 2.x code (global locationPicker, getMarkerPosition, setCurrentPosition). license: MIT metadata: homepage: https://cyphercodes.github.io/location-picker/ repository: https://github.com/cyphercodes/location-picker

location-picker

location-picker captures one precise point: the user pans a map under a fixed centre pin (or searches, pastes coordinates, or taps "Use my location"), and the page gets "lat,lng". It ships a form-associated custom element, <location-picker>, and an imperative class, LocationPicker. The default map is OpenStreetMap through Leaflet, with no API key.

Do not use it for drawing shapes or routes, several markers, a full mapping application, or text-only address autocomplete.

Steps

  1. Pick the entry point.
    • No bundler: <script src="https://cdn.jsdelivr.net/npm/location-picker@3"></script> (keep the @3). It defines <location-picker> and window.LocationPicker.
    • Bundler: npm i location-picker, then import 'location-picker' once in client code. It defines the element and is a no-op on the server.
    • Need the engine map synchronously, or no custom element: import { LocationPicker } from 'location-picker/core'.
  2. Wire the value. In a form, use name (one "lat,lng" field), lat-name + lng-name (two fields), or lat-input + lng-input (fill inputs the page already has). In a framework, bind value and update state from change (committed); use input only to display live updates, and never write the value back from an input listener (in 3.0 that stops a pan in progress). Use the per-framework event names below.
  3. Choose the provider. Leave it out for OpenStreetMap. For Google Maps add provider="google" api-key="YOUR_BROWSER_KEY". For MapLibre, the project must provide maplibre-gl and its CSS.
  4. Choose the presentation. Default inline (the map in the page). For checkout, delivery or sign-up forms that people fill in on phones, use presentation="auto": a compact field with a "Choose on map" button on phones, the inline map elsewhere. In field mode ready resolves at the first open, so never gate the form on el.ready.
  5. Add features only when asked: search, reverse-geocode (with address-name or addresschange), locate="button", required, center and zoom.
  6. Check the result against "Common mistakes" before you finish.

If the user has no code at all (WordPress, Webflow, Squarespace, Shopify, a Formspree or Netlify form), point them to the snippet generator at https://cyphercodes.github.io/location-picker/embed/ and the platform guide https://github.com/cyphercodes/location-picker/blob/master/docs/embed.md. If an agent or a bot only needs to ask a person for a location, use the pick link (below) instead of building a page.

Plain HTML

<!doctype html>
<html lang="en">
<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<title>Pick a location</title>
<script src="https://cdn.jsdelivr.net/npm/location-picker@3"></script>
<label for="where">Where is it?</label>
<location-picker id="where" search locate="button" style="height: 400px"></location-picker>
<p>Picked: <output id="out">nothing yet</output></p>
<script>
  document.getElementById('where').addEventListener('change', (e) => {
    document.getElementById('out').textContent = e.detail.value; // "48.85837,2.294481"; e.detail has lat, lng, source, address
  });
</script>
</html>

Forms and server-rendered pages

The element submits like an input. Existing hidden inputs (the most common pattern in Laravel, Django, Rails, PHP and Express apps) are filled by the picker and get native input/change events, which jQuery, Livewire and Alpine listen to. Their server values seed the picker, and a form reset restores them.

<form method="post" action="/places">
  <input type="hidden" name="lat" id="lat" value="48.8584" />
  <input type="hidden" name="lng" id="lng" value="2.2945" />
  <label for="loc">Location</label>
  <location-picker
    id="loc"
    lat-input="lat"
    lng-input="lng"
    required
    search
    style="height: 360px"
  ></location-picker>
  <button>Save</button>
</form>
<script src="https://cdn.jsdelivr.net/npm/location-picker@3"></script>
  • name="loc" submits loc=48.85837,2.294481; lat-name="lat" lng-name="lng" submits two fields; address-name="addr" adds the address (needs search or reverse-geocode).
  • Progressive enhancement: put the inputs inside <location-picker>; without JavaScript they are visible and typeable.
  • Validate on the server too: latitude in [-90, 90], longitude in [-180, 180].

Phones: field mode

<form method="post" action="/deliveries">
  <label for="drop">Delivery spot</label>
  <location-picker id="drop" presentation="auto" name="location" search locate="button" reverse-geocode required></location-picker>
  <button>Continue</button>
</form>
<scr
阅读完整来源 ↗