<wc-location-field>

A self-contained web component for location selection. Provides address search via Nominatim (OpenStreetMap) or Google Maps, an optional interactive map, browser geolocation, and optional What3Words integration. No framework dependencies.

Demo

<custom-element-demo>
  <template>
    <script src="https://unpkg.com/@annoyingmouse/wc-location-field/wc-location-field.js" defer></script>
    <next-code-block></next-code-block>
  </template>
</custom-element-demo>

<wc-location-field
  label="Find a location"
  placeholder="e.g. Paddington Station"
></wc-location-field>

Installation

<script src="https://unpkg.com/@annoyingmouse/wc-location-field/wc-location-field.js" defer></script>

Styles and Leaflet (when show-map is used) are loaded automatically — no extra <link> tags needed.

Or as a module:

<script type="module" src="https://cdn.skypack.dev/@annoyingmouse/wc-location-field/wc-location-field.js"></script>

Usage

<wc-location-field label="From" placeholder="e.g. Paddington Station"></wc-location-field>

With map (Nominatim/Leaflet):

<wc-location-field
  label="Meeting point"
  show-map
  center-lat="51.505"
  center-lng="-0.09"
></wc-location-field>

With Google Maps (Places Autocomplete + Google Maps map):

<wc-location-field
  label="Meeting point"
  map-provider="google"
  google-maps-key="YOUR_API_KEY"
  show-map
></wc-location-field>

Display-only pinned map (no search UI, no click/drag):

<wc-location-field
  id="venue"
  label="Venue"
  show-map
  readonly
></wc-location-field>

document.querySelector('#venue').prefill({ address: 'Buckingham Palace', lat: 51.5014, lng: -0.1419 })

Attributes

| Attribute | Description | |---|---| | label | Field label text (reactive) | | placeholder | Input placeholder text (reactive) | | center-lat / center-lng | Map centre and search bias | | show-map | Renders an interactive map below the search box | | readonly | Hides search UI and disables map click/drag; use with show-map and prefill() to display a pinned location | | map-provider | "nominatim" (default) or "google" | | google-maps-key | Google Maps API key — required when map-provider="google" | | w3w-key | What3Words API key; enables ///word.word.word search | | radius-km | Draws a circle overlay on the map (requires show-map, center-lat, center-lng) |

Public API

const field = document.querySelector('wc-location-field')

// Programmatically set a location (does not fire location-change)
field.prefill({ address: 'Buckingham Palace', lat: 51.5014, lng: -0.1419 })

// Reset
field.clear()

// Read state
console.log(field.value, field.lat, field.lng, field.address)
// field.value returns What3Words address when resolved, else formatted address, else raw input

// label and placeholder can also be set as JS properties
field.label = 'Destination'
field.placeholder = 'Search for a place…'

// Set a GeoJSON boundary overlay on the map (polygon/feature drawn, map centred on its bounds)
field.geojson = { type: 'Polygon', coordinates: [[[0.1, 52.3], [0.2, 52.3], [0.2, 52.4], [0.1, 52.4], [0.1, 52.3]]] }

Events

field.addEventListener('location-change', e => {
  const { lat, lng, address, w3w } = e.detail
})

The location-change CustomEvent bubbles and fires whenever a location is resolved (from search, map click, marker drag, or geolocation).

Theming

The component is intentionally minimal — input and button styling inherit from your page. Two CSS custom properties are available:

wc-location-field {
  --lf-map-height: 300px;   /* default: 240px */
  --lf-w3w-color: #e11f26;  /* What3Words /// prefix colour */
}

Accessibility

• ARIA combobox pattern (role="combobox", aria-expanded, aria-haspopup="listbox", aria-activedescendant)
• Full keyboard navigation: ArrowDown/ArrowUp to move through suggestions, Enter to select, Escape to dismiss
• Coordinates announced via aria-live="polite"
• Geolocation status and errors announced via aria-live="assertive"
• GPS button has an accessible label
• In readonly mode the map container is labelled aria-label="Location map" for screen readers

Development

No build step required. Open index.html directly in a browser to develop and test.

npm run format   # format with Biome
npm run lint     # lint with Biome
npm test         # run tests with Web Test Runner

Releasing

Before releasing for the first time, authenticate with npm:

npm login

Then use one of the release scripts depending on the change:

npm run release:patch   # bug fixes (1.0.5 → 1.0.6)
npm run release:minor   # new features (1.0.5 → 1.1.0)
npm run release:major   # breaking changes (1.0.5 → 2.0.0)

Each script:

1. Bumps the version in package.json and creates a git commit and tag
2. Builds the minified dist (dist/wc-location-field.min.js) via Rollup
3. Syncs the new version into bower.json
4. Commits the build artifacts, pushes the commit and tags to GitHub
5. Publishes the package to npm with public access

Licence

MIT