Geocode Earth Autocomplete Element

An autocomplete element (Web Component) for use with the Geocode Earth Autocomplete API.

Installation

$ npm install @geocodeearth/autocomplete-element

The package is also available via GitHub Packages.

Then import it:

import '@geocodeearth/autocomplete-element'

You can also use a script tag referencing it locally:

<script type="module" src="https://github.com/geocodeearth/autocomplete-element/raw/main/node_modules/@geocodeearth/autocomplete-element/dist/bundle.js"></script>

Basic Usage

Once installed you can use the custom element:

<ge-autocomplete api_key='ge-YOURKEY'></ge-autocomplete>

Attributes

All configuration happens through attributes on the element. api_key is the only required one (as without it you can’t access the API). All other available attributes are documented below.

`api_key`

required, no default

Your Geocode Earth API key. Sign up for a free trial »

`throttle`

defaults to 200

Used to prevent firing a request for every keystroke as the user types, in milliseconds. This is passed directly to the _.throttle function.

`size`

defaults to 10

Controls how many results should be shown.

`placeholder`

defaults to Search a city or address

Sets the placeholder text for the input field.

`autofocus`

defaults to false

Sets whether the input should be automatically focused, can be set without an explicit value as it’s a boolean:

<ge-autocomplete api_key="…" autofocus></ge-autocomplete>

`lang`

defaults to Accept-Language header, falls back to en

Sets the language in which results are returned.

`layers`

defaults to all layers

The Geocode Earth dataset is a combination of multiple data layers. This attribute can be used to limit results to a specific layer (or multiple ones, comma separated). Please see our API documentation for a list of available layers: geocode.earth/docs/reference/data_layers/

`focus.point.lat` & `focus.point.lon`

defaults to unfocused

Sets latitude and longitude around which to focus results. In addition to providing results that are more relevant due to their proximity, setting a focus point is generally significantly faster than an unfocused query.

`boundary.country`

defaults to unset (all countries)

Sets a country filter to only return results in the specified country. Use a comma separated list of ISO 3166-1 country codes (2 or 3 letter variants).

`boundary.gid`

defaults to unset (all GIDs)

Filters results by parent ID, which can be used to search in areas smaller than a country and/or areas with shapes not well represented by rectangular bounding boxes.

Please see our documentation how to use this.

`boundary.circle.lat`, `boundary.circle.lon`, `boundary.circle.radius`

defaults to unset

Searches within a circular region. Useful to return results in a radius around a known point. Note: all three parameters need to be set. The radius is defined in kilometers.

`boundary.rect.min_lat`, `boundary.rect.max_lon`, `boundary.rect.max_lat`, `boundary.rect.min_lon`

defaults to unset

Searches within a rectangular region. Same as with a circular boundary all 4 parameters have to be set.

Tip: You can look up a bounding box for a known region using geojson.io.

Events

The element also emits events as a user interacts with it. This is how you can be notified when a user selects a result, for example. The event.detail payload contains details about the event.

Note: These events do not bubble, which means listeners have to be attached to the element directly (see examples below).

Event Name	`event.detail`	Description
`select`	`Feature`	Dispatched when a user selects a suggested item from the list.
`change`	`string`	Dispatched with every keystroke as the user types (not debounced).
`features`	`[]Feature`	Dispatched when the GeoJSON features backing the UI change.
`error`	`Error`	Dispatched if an error occures during the request (for example if the rate limit was exceeded.)

Customization

We did our best to design the element in such a way that it can be used as is in a lot of different contexts without needing to adjust how it looks. However, there certainly can be situations where customization is necessary. The element supports three different customization APIs:

Custom CSS (variables)
A string template as well as
A row template

1. Custom CSS

We use CSS variables for almost all properties that you would want to customize. This includes the font family, background or shadow of the input and the hover state for a result just to name a few. For a list of all available variables please check the source CSS file directly (/src/autocomplete/autocomplete.css).

You can adjust these variables by placing a <style> tag inside the element, like so:

<ge-autocomplete api_key="…">
  <style>
     :host {
       --input-bg: salmon;
       --input-color: green;
       --loading-color: hotpink;
    }
  </style>
</ge-autocomplete>

Important: While it is technically possible to override the actual classnames the element uses internally, we do not consider those part of the public API. That means they can change without a new major version, which could break your customization. The CSS variables on the other hand are specifically meant to be customized, which is why they will stay consistent even if the internal markup changes.

If you would like to customize a property for which there is no variable we’d be happy to accept a pull-request or issue about it.

2. String Template

If you want to customize how a feature is turned into a string for rendering (in the results as well as the input field after it was selected), you can define a custom string template. This allows you to use the lodash template language to access every property of the feature to build a custom string.

<ge-autocomplete api_key="…">
  <template string>
    ${item.feature.properties.name} (${item.feature.properties.id}, ${item.feature.properties.source})
  </template>
</ge-autocomplete>

Important: Make sure to return a plain string here, no HTML. The reason for this is that this template will also be used in the input field itself after a result has been selected, which doesn’t support HTML.

3. Row Template

Similar to the string template mentioned above, you can use the row template to define how a single row in the results is rendered. The key here is that this supports full HTML:

<ge-autocomplete api_key="…">
  <template row>
    <div class="custom-row ${item.active ? 'custom-row--active' : null}">
      <img src="https://github.com/geocodeearth/autocomplete-element/raw/main/flags/${item.feature.properties.country_a.png}" alt="${item.feature.properties.country_a}">
      <span>${item.feature.properties.label}</span>
    </div>
  </template>
</ge-autocomplete>

Pro Tip™: Use the item.active property to check if the current row is being hovered over or activated via arrow keys. See below for additional properties.

The example above could render a little flag icon for the result’s country, for example. You can customize the styling by defining custom classes in the same way you would customize the CSS variables. It’s best to prefix your classes to avoid conflicts with internal classnames of the element.

The lodash template language supports much more than just straight variables. Please refer to their docs directly to understand how it works. It’s pretty powerful.

Additional Template Properties

Inside a template you can access the following properties:

Property	Type	Contains
`item.feature`	Object	The selected item, a GeoJSON Feature
`item.active`	Boolean	Whether or not the current item is active (hovered or selected with arrow keys)
`item.searchTerm`	String	The current value of the search input field
`item.index`	Number	The index of the item in the result list

Example

Please see the example folder. You can follow the steps in the Development section to run them directly, too.

Development

$ npm install
$ npm run dev

License

This code is licensed under the MIT license. Please see the LICENSE file for details.