Address Search & Location Picker Web Component with Maps - wc-location-field

Authorannoyingmouse

Last UpdateAugust 3, 2026

LicenseMIT

Features:

Address autocomplete via Nominatim or Google Maps.
Renders an optional interactive OpenStreetMap or Google map.
Retrieves the browser’s current geographic position.
Accepts locations from search results, map clicks, and marker dragging.
Exposes addresses and coordinates through public state properties.
Displays fixed map pins in a read-only mode.
Supports What3Words searches and coordinate conversion.
Draws radius circles and GeoJSON boundary overlays.
Loads its base styles and Leaflet assets automatically.
Supports keyboard navigation and ARIA combobox semantics.
Works in plain HTML pages.

How To Use It:

Installation

Load the component before adding the custom element to the page. The script registers the <wc-location-field> element and adds its base stylesheet to the document. Leaflet CSS and JavaScript load automatically after a component with the show-map attribute connects to the page.

<script
  src="/path/to/dist/wc-location-field.min.js"
  defer
></script>

Basic Usage

Add the custom element wherever the form needs an address field. The default provider sends search queries to Nominatim and does not display a map. In this example, search begins after the visitor enters at least three characters. Selecting a suggestion resolves the address and coordinates, then dispatches the location-change event.

<form id="delivery-form">
  <wc-location-field
    id="delivery-location"
    label="Delivery address"
    placeholder="Search for a street or place"
  ></wc-location-field>
  <input id="delivery-latitude" name="latitude" type="hidden">
  <input id="delivery-longitude" name="longitude" type="hidden">
  <button type="submit">Save Address</button>
</form>
<script>
  const locationField = document.querySelector('#delivery-location');
  const latitudeInput = document.querySelector('#delivery-latitude');
  const longitudeInput = document.querySelector('#delivery-longitude');
  locationField.addEventListener('location-change', function (event) {
    latitudeInput.value = event.detail.lat;
    longitudeInput.value = event.detail.lng;
  });
</script>

Add an OpenStreetMap Location Picker

The show-map attribute adds a Leaflet map below the search field. Visitors can choose a position from an address result, click the map, or drag the marker.

<wc-location-field
  id="meeting-location"
  label="Meeting point"
  placeholder="Search near downtown"
  show-map
  center-lat="40.7128"
  center-lng="-74.0060"
></wc-location-field>

Use Google Maps and Places Autocomplete

Set map-provider to google when the project requires Google Places predictions or a Google map. A valid Google Maps API key must be supplied through google-maps-key.

<wc-location-field
  id="hotel-location"
  label="Hotel or destination"
  placeholder="Search for a hotel, address, or landmark"
  map-provider="google"
  google-maps-key="YOUR_GOOGLE_MAPS_API_KEY"
  show-map
></wc-location-field>

Display a Read-Only Pinned Map

The readonly attribute removes the input, suggestion list, and GPS button. It also disables map clicks and marker dragging.

Add show-map, then supply the location through prefill().

<wc-location-field
  id="office-map"
  label="Main office"
  show-map
  readonly
></wc-location-field>
<script>
  const officeMap = document.querySelector('#office-map');
  officeMap.prefill({
    address: '350 Fifth Avenue, New York, NY',
    lat: 40.7484,
    lng: -73.9857
  });
</script>

Add What3Words Search

A What3Words API key activates searches in the ///word.word.word format. The same integration resolves selected coordinates to a three-word address.

The value property returns the What3Words address when one has been resolved. It falls back to the formatted address and then the raw input value.

<wc-location-field
  id="field-location"
  label="Exact field location"
  placeholder="Enter an address or ///three.word.address"
  w3w-key="YOUR_WHAT3WORDS_API_KEY"
  show-map
></wc-location-field>

Draw a Radius Around a Search Area

The radius-km attribute draws a circle around the coordinates supplied through center-lat and center-lng.

<wc-location-field
  label="Service location"
  show-map
  center-lat="34.0522"
  center-lng="-118.2437"
  radius-km="15"
></wc-location-field>

Display a GeoJSON Boundary

Assign a GeoJSON geometry, feature, or feature collection to the geojson property after the component exists in the DOM.

<wc-location-field
  id="coverage-map"
  label="Coverage area"
  show-map
></wc-location-field>
<script>
  const coverageMap = document.querySelector('#coverage-map');
  coverageMap.geojson = {
    type: 'Polygon',
    coordinates: [[
      [-73.997, 40.744],
      [-73.981, 40.744],
      [-73.981, 40.756],
      [-73.997, 40.756],
      [-73.997, 40.744]
    ]]
  };
</script>

Available Attributes

label (string): Sets the text displayed above the field. Changes made after initialization update the visible label.
placeholder (string): Sets the address input placeholder. The default is Search for a location….
center-lat (number): Sets the initial map latitude and geographic search bias.
center-lng (number): Sets the initial map longitude and geographic search bias.
show-map (boolean): Adds an interactive map below the search field.
readonly (boolean): Hides the search controls and disables map interaction. Pair it with show-map and prefill().
map-provider (string): Selects nominatim or google. The default value is nominatim.
google-maps-key (string): Supplies the required Google Maps API key for the Google provider.
w3w-key (string): Activates What3Words suggestions and coordinate conversion.
radius-km (number): Draws a circle with the specified radius in kilometers around the center coordinates.

Public API

const field = document.querySelector('#delivery-location');
// Set an address and coordinates programmatically.
// This call does not dispatch location-change.
field.prefill({
  address: '1 Market Street, San Francisco, CA',
  lat: 37.7936,
  lng: -122.3958
});
// Clear the address, coordinates, suggestions, and map marker.
field.clear();
// Read the current location state.
console.log(field.value);
console.log(field.address);
console.log(field.lat);
console.log(field.lng);
console.log(field.w3w);
// Update reactive text properties.
field.label = 'Destination';
field.placeholder = 'Search for an address';
// Add a GeoJSON geometry, Feature, or FeatureCollection.
field.geojson = {
  type: 'Point',
  coordinates: [-122.3958, 37.7936]
};
// Read the current GeoJSON overlay data.
console.log(field.geojson);

value follows this priority order:

Resolved What3Words address.
Resolved formatted address.
Current raw input text.
An empty string.

The w3w property returns null when the integration has not resolved a three-word address.

Events

The component dispatches one bubbling custom event after it resolves a location from a search result, map click, marker drag, or browser geolocation request.

const field = document.querySelector('#delivery-location');
field.addEventListener('location-change', function (event) {
  const { lat, lng, address, w3w } = event.detail;
  console.log('Latitude:', lat);
  console.log('Longitude:', lng);
  console.log('Address:', address);
  console.log('What3Words:', w3w);
});

Calling prefill() does not dispatch this event. Run any dependent application logic manually after a programmatic update.

Styling and Customization

The component supports two CSS custom properties: --lf-map-height changes the map height, and --lf-w3w-color changes the What3Words prefix color.

--lf-map-height: Sets the map height. The default is 240px.
--lf-w3w-color: Sets the color of the /// prefix in What3Words suggestions. The default is #e11f26.

wc-location-field {
  --lf-map-height: 320px;
  --lf-w3w-color: #c81e1e;
}

The component renders its controls in the light DOM. Page-level CSS can target the generated input and button directly. Use element selectors or project-owned wrapper selectors for additional styling.

wc-location-field input {
  min-height: 44px;
  padding: 0.65rem 0.8rem;
  border: 1px solid #b8bec7;
  border-radius: 6px;
}
wc-location-field button {
  min-width: 44px;
  min-height: 44px;
  border: 1px solid #b8bec7;
  border-radius: 6px;
}

Alternatives:

FAQs:

Q: Do I need an API key to use the default setup?
A: No. With map-provider left unset, address search runs through Nominatim and mapping through Leaflet and OpenStreetMap tiles.

Q: What happens if I set map-provider="google" without a google-maps-key?
A: The component logs a console warning and does not initialize the Google Maps script.

Q: Can I use this inside a React or Vue application?
A: Yes. It is a standard custom element, so it can be dropped into JSX or a Vue template like any other tag, with label and placeholder set as either attributes or DOM properties.

Q: Does the field work without JavaScript geolocation permission?
A: Yes. Denying or lacking geolocation only disables the GPS button; address search, the map, and manual pin placement continue to work normally.

Q: How do I show a saved location without letting the user change it?
A: Add readonly and show-map, then call prefill() with the saved address and coordinates once the element is connected to the page.

Q: Why are Google Maps suggestions not loading?
A: Confirm that map-provider="google" and google-maps-key are present. Check the domain restrictions, billing status, and Maps and Places API settings in the Google Cloud project.

Address Search & Location Picker Web Component with Maps – wc-location-field