Autocomplete Element

This guide covers how to quickly add a fast, configurable and easy-to-use address autocompletion element to any web app or web page.

In just a few minutes, you’ll have a responsive, interactive <input> element like this:

Installation #

The autocomplete element is available through npm or the traditional <script> tag.

Pre-bundled version via HTML script tag #

We maintain an up to date, minified version of the autocomplete element available via CDN.


Full Package via NPM #

This option will work best if you’re already using webpack or another tool for managing JavaScript dependencies.

With a modern version of node installed:

npm install @geocodeearth/autocomplete-element --save
import '@geocodeearth/autocomplete-element'

Basic Usage #

To get started, you only need your Geocode Earth API key and one line of HTML.

  api_key="<YOUR API KEY>"

Using Autocomplete endpoint filters #

The autocomplete endpoint supports numerous filtering options, and all of them are supported by the autocomplete element.

Here are a few common examples, each with their own live demo.

Restricting results to a few countries #

The parameter allows restricting results to a list of one or more countries.

  api_key="<YOUR API KEY>""US,CA,MX"
  placeholder="Search for places in North America"

Preferring results near a lat/lon coordinate #

The and focus.point.lon allow biasing results to those closer to the given coordinate.

  api_key="<YOUR API KEY>""21.30"
  placeholder="Search for places near Honolulu, Hawaii"

Restricting results to a single city #

The boundary.gid parameter accepts any parent ID returned by other queries to Geocode Earth.

  api_key="<YOUR API KEY>"
  placeholder="Search for places in Barcelona, Spain"

Events #

The HTML element emits events, attaching event listeners allows your application to be notified when the user interacts with the element.

The event.detail payload contains details about each event.

// find the first matching ge-autocomplete element
const el = document.querySelector('ge-autocomplete')

// 'select' event handler - when a user selects an item from the suggestions
el.addEventListener('select', (event) => {
  console.log(event.detail, event)

// 'change' event handler - on every keystroke as the user types
el.addEventListener('change', (event) => {
  console.log(event.detail, event)

// 'features' event handler - when the GeoJSON features backing the UI change
el.addEventListener('features', (event) => {
  console.log(event.detail, event)

// 'error' event handler - on error
el.addEventListener('error', (event) => {
  console.log(event.detail, event)

Visual Customization #

The Github documentation outlines a variety of options for customizing the visual appearance of the element:

Feedback & Feature Requests #

If you find a bug, or would like to request a feature, please open an issue on Github.