Using the JavaScript AutoSuggest Component (v4.0)

easy

The easiest way to add what3words to your technology is to use one of our components. We have components available for JavaScript, iOS and Android which require minimal development to integrate.

The AutoSuggest Component allows users to quickly and correctly input a 3 word address to a form input or search field by providing suggestions as a user types and validation to ensure the input value is a valid 3 word address. The component by default uses the what3words API or can be configured to use a privately hosted instance of the what3words API.

This tutorial steps through how our JavaScript AutoSuggest Component can be added to a website and how it can be customised to refine the 3 word address suggestions displayed and how it can inherit the style of your site.

The JavaScript components can be added to any site using JavaScript and HTML. Find out how else you can utilise the what3words API using JavaScript by taking a look at the functions in the what3words JavaScript API Wrapper

You will need a what3words API key to complete this tutorial.

2

Add component

my answer

Installation

Include the what3words.js script on each page of your site that you would like to use the component on. You will need to replace YOUR-API-KEY with your what3words API key. Alternatively, you can remove this parameter and add the API key as an attribute to the component element.

<script type="module" src="https://cdn.what3words.com/javascript-components@4-latest/dist/what3words/what3words.esm.js"></script>
<script nomodule src="https://cdn.what3words.com/javascript-components@4-latest/dist/what3words/what3words.js?key=YOUR-API-KEY"></script>
Copied

Versioning

The AutoSuggest Component is versioned to allow for updates and bug fixes. We recommend using @4-latest to specify that the latest version of the current major version is loaded. This will ensure that the component is loaded without any breaking changes but receives the benefits of bug fixes and new features.

A specific version can also be specified within the script to ensure a predictable version of the component is loaded, for example@4.0.1.

<script type="module" src="https://cdn.what3words.com/javascript-components@4-latest/dist/what3words/what3words.esm.js"></script>
<script nomodule src="https://cdn.what3words.com/javascript-components@4-latest/dist/what3words/what3words.js?key=YOUR-API-KEY"></script>
Copied
<script type="module" src="https://cdn.what3words.com/javascript-components@4.0.1/dist/what3words/what3words.esm.js"></script>
<script nomodule src="https://cdn.what3words.com/javascript-components@4.0.1/dist/what3words/what3words.js?key=YOUR-API-KEY"></script>
Copied

Extending an input with AutoSuggest functionality

The what3words AutoSuggest Component is a container tag that wraps around an input element. You can either extend an existing input that is to be used as a what3words field or add a new one and wrap the what3words autosuggest container tags what3words-autosuggest around the input.

<what3words-autosuggest>
  <input type="text">
</what3words-autosuggest>
Copied

Including a label and placeholder as well as making the field optional is recommended particularly when used as part of an input field for a checkout page.

<label for="w3w">what3words (optional):</label>
<what3words-autosuggest>
  <input
    placeholder="e.g. ///lock.sprout.radar"
    type="text"
    name="w3w"
    id="what3words"
    optional
  />
</what3words-autosuggest>
Copied

Configuring for use with API server

If you run our Enterprise Suite API Server yourself, you may specify the URL to your own server by appending the baseUrl parameter to the script loaded.

<script type="module" src="https://cdn.what3words.com/javascript-components@4-latest/dist/what3words/what3words.esm.js"></script>
<script nomodule src="https://cdn.what3words.com/javascript-components@4-latest/dist/what3words/what3words.js?key=YOUR-API-KEY&baseUrl=https://example.com/v3"></script>
Copied
3

Styling component

Default variant

By default, the component will load with our predefined style. Elements of the component can then be overridden using CSS by specifying new values for the classes used by the component:

.what3words-autosuggest-input-wrapper > input {
  font-weight: 800;
}
Copied

Inherit variant

We strongly recommend that if you have your own styling set up in your site for other input elements that you use the component’s variant=inherit attribute. This attribute removes the default styling which allows you to easily modify the input style used by the component to match the others on your form.

<what3words-autosuggest variant="inherit">
  <input type="text">
</what3words-autosuggest>
Copied

The dropdown and error message used by the component are unaffected by the variant attribute to ensure that the layout of the suggestions is optimal. It is, however, possible to override the style of the dropdown too if desired using CSS overrides.

4

Localising component

Supported languages

The AutoSuggest Component will accept any 3 word address in any language supported by the what3words API. It can also be added to a site using a right to left language as long as the HTML direction has been set, for example:

<html dir="rtl" lang="ar">
Copied

Localising errors

The error message displayed by the component if a valid 3 word address has not been added can be changed to support location. This can be changed using the attribute error_message:

<what3words-autosuggest invalid_address_error_message="Aucune adresse trouvée">
  <input type="text">
</what3words-autosuggest>
Copied

Country clipping

In order to refine the suggestions supplied to a user we recommend using country clipping where appropriate. If, for example, the component is to be used on a checkout page then country clipping can be specified using the clip_to_country attribute for the delivery country to ensure that only suggestions are shown in that country and closer matches are displayed. Multiple countries can be specified comma-separated.

<what3words-autosuggest clip_to_country="GB">
  <input type="text">
</what3words-autosuggest>
Copied

Focus

In addition to country clipping, it is also possible to add focus to results using the autosuggest_focus attribute. The focus should be supplied as a lat, long, usually the user’s location from the GPS on their device. Supplying focus will ensure that suggestions displayed to the user are biased to their location.

<what3words-autosuggest autosuggest_focus="51.1,2.0">
  <input type="text">
</what3words-autosuggest>
Copied
5

Attributes

Component script parameters

ParameterTypeDescription
keyStringAn API key is required for the component to function correctly. Example: key=Your-API-Key
baseUrlStringThe component can be used with an Enterprise Suite API Server instance by using baseUrl. Example: baseUrl=https://example.com/v3
callbackStringAllows for a callback to be fired once the component has loaded. This should be the function name to be fired. Example: callback=initMap
headersStringEnterprise API Server only - Allows for custom headers to be passed through in requests.

Recommended input element attributes

AttributeTypeDescription
nameStringStandard CSS name. Example: name="what3words"
idStringStandard CSS input ID. If not specified then one will be added by our component. Example: id="what3words"
classStringStandard CSS class - use with the variant=inherit attribute to apply this class to the input element of the component. Example: class="input-field"
valueStringSets the initial value of the input element. We recommend always including the /// before the 3 word address. Example: value="///filled.count.soaop"
placeholderStringPlaceholder text to display. We recommend keeping the placeholder as a 3 word address proceeded with "e.g." Example: placeholder="e.g ///filled.count.soap"

Component attributes

AttributeTypeDescription
api_keyStringAPI Key can be specified as an attribute to the component if it can't be specified at in the script. Example: api_key="Your-API-Key"
variantStringVariant attribute allows for a different variant style to be applied to the input element. variant=inherit allows for the component to inherit the style from a CSS class to match other inputs on a site. A class should be specified on the input in conjunction with variant=inherit. Example: variant="inherit"
invalid_address_error_messageStringOverwrites the error message with a custom value. Example value:"You have entered an invalid address"
languageStringAllows you to add a preferred suggestion fallback language. Only used when input value language cannot be determined. Example: language="EN"
autosuggest_focus StringComma separated lat/lng of a point to focus on AutoSuggest results on. This is useful to focus results on a users location. Example value: autosuggest_focus="51.521251,-0.203586"
n_focus_resultsNumberThe number of AutoSuggest results to apply the focus to. Example: n_focus_results="2"
clip_to_countryStringRestrict suggestions to a given country or comma separated list of countries. Example: clip_to_country="GB,US"
clip_to_bounding_boxStringRestrict suggestions to a bounding box specified using co-ordinates. Example: clip_to_bounding_box="51.521,-0.343,52.6,2.3324"
clip_to_circleStringRestrict suggestions to a circle, specified by lat,lng,kilometres, where kilometres is the radius of the circle. Example: clip_to_circle="51.521251,-0.203586,2"
clip_to_polygonStringRestrict suggestions to a polygon, specified by a comma-separated list of lat,lng pairs. The polygon should be closed, i.e. the first element should be repeated as the last element; also the list should contain at least 4 entries. The API is currently limited to accepting up to 25 pairs. Example: clip_to_polygon="51.521,-0.343,52.6,2.3324,54.234,8.343,51.521,-0.343"
return_coordinatesBooleanMakes an additional call to the what3words API to obtain the coordinates for the selected 3 word address. Note this will use a convert-to-coordinates call whereas without this property only AutoSuggest API calls are made. Example: return_coordinates=true
6

Events

EventDescription
value_changedFired when the value entered into the input changes
value_validFired when a valid 3 word address has been selected from the suggestions
value_invalidFires when input value is not a valid 3 word address
selected_suggestionFires when a suggestion is selected from the dropdown.
suggestions_changedFires when the suggestions displayed in the dropdown change
coordinates_changedOnly when return_coordinates attribute has been enabled. Fires when coordinates change when a new valid 3 word address is selected.

Listening for events

Using an event listener it is possible to fire other functionality in a site when something changes in the AutoSuggest Component. For example, it is possible to listen for when a valid 3 word address has been entered and update another element in the page or to listen for when new coordinates have been returned and pan/zoom a map to the location.

const autosuggest = document.getElementById("what3words");
      autosuggest.addEventListener(
        "selected_suggestion",
        ({
          detail: {
            suggestion: { words }
          }
        }) => {
          console.log("Suggestion selected");
        }
      );
Copied
7

Versions

The following table outlines the release versions of the AutoSuggest Component.

VersionDateDetails
4.0.025/05/2021New release of the AutoSuggest Component
4.0.108/06/2021Bug fix release

Related tutorials

Back to top