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 JavaScript component can also be used in React.js and Vue.js.

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 either for static pages or using npm 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 .

Getting started with Christian, what3words Lead Frontend Developer:

Quickstart

The AutoSuggest Component requires just a few lines of code to be added to a form to create a what3words powered input field. ReplaceYOUR-API-KEY with your what3words API key.

<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>

<form id="form" method="GET">
   <div>
      <what3words-autosuggest>
        <input type="text" />
      </what3words-autosuggest>
   </div>
</form>
Copied

Step by Step

1
2

Add component

Installation

The component can be added to static HTML pages by including the what3words.js script on each page of your site that you would like to use the component on. You will need to replaceYOUR-API-KEY with your what3words API key. You can also remove this parameter and add the API key as an attribute to the component element instead.

Alternatively, if you are using npm within your site you can consume one of our packages for your framework:

<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. If installing using HTML 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 . A log of versions can be found here

<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 aninput 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 around the input.
When adding using HTML you can either add the what3words API key to the script in the header or specify as an attribute to the container.

<what3words-autosuggest api_key="YOUR-API-KEY">
  <input type="text" />
</what3words-autosuggest>
Copied

You will also need to add animport line to our package if you are using npm. Adding 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. ///filled.count.soap"
    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 thebaseUrl parameter to thescript loaded. Using the frameworks you can specify thebaseUrl usingwindow.what3words.api.setOptions

<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

By default, the JavaScript AutoSuggest Component will load with the what3words predefined style. Whether you have an e-commerce store or a web application, you can match the style of your own site by overriding:

  • CSS class attribute of the Input;
  • variant attribute of the component;
  • what3words address suggestions provided by the component.

Override CSS class

The Input element attributes can be overridden by specifying new CSS values for classes used by the component. For example, you can give the input aclass="input-field" and then use CSS to style as it is shown in our example.

Note: recommended using with thevariant="inherit" component attribute for the JavaScript AutoSuggest component to inherit the style from a CSS class to match other inputs on your site.

Please visit this interactive code sample to quickly and easily use this solution.

<style>
  .input-field {
    width: 100%;
    font-size: 16px;
    border-width: 0px;
    border-color: #000000;
    background-color: #ffffff;
    color: #000000;
    border-style: outset;
    border-radius: 0px;
    box-shadow: 0px 0px 5px rgba(66, 66, 66, 0.75);
    margin-top: 5px;
    outline: none;
  }
</style>
Copied

Use 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’svariant="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.

Note: variant="inherit" attribute should be applied to the component as it shown below.

Please visit this interactive code sample to quickly and easily use this solution

Styling Input

<what3words-autosuggest api_key="YOUR-API-KEY" variant="inherit">
  <input
    type="text"
    id="what3words"
    name="what3words"
    class="input-field"
    optional
  />
</what3words-autosuggest>
Copied

Override what3words address suggestions

The what3words address suggestions 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 what3words address suggestions provided by the component too if desired using CSS overrides to match the styling of your own site.

Please visit this interactive code sample to quickly and easily use this solution

Override the style of the Dropdown

<style>
  .what3words-autosuggest-item {
    background: #ebebeb !important;
    padding: 0px !important;
    box-shadow: none !important;
  }
  .what3words-autosuggest-item .match {
    background: #fcfcfc !important;
    box-shadow: none !important;
  }
  .what3words-autosuggest-item:hover {
    background: #f9f9f9 !important;
    box-shadow: none !important;
  }
  .what3words-autosuggest-item .active,
  .what3words-autosuggest-item:active {
    background: #fc9fc9 !important;
    box-shadow: none !important;
  }
  .what3words-autosuggest-address {
    height: auto !important;
    font-weight: inherit !important;
    font-size: inherit !important;
    line-height: inherit !important;
    color: inherit !important;
  }
  .what3words-autosuggest-address > .what3words-autosuggest-words {
    width: auto !important;
    white-space: inherit !important;
    overflow: inherit !important;
    text-overflow: inherit !important;
  }
  .what3words-autosuggest-nearest-place {
    padding: 0px 0px 0px 18px !important;
  }
  .what3words-autosuggest-nearest-place-text {
  }
  .what3words-autosuggest-nearest-place-text > div:first-child {
    font-size: inherit !important;
    line-height: inherit !important;
    color: inherit !important;
    text-overflow: inherit !important;
  }
  .what3words-autosuggest-nearest-place-distance {
    font-weight: inherit !important;
    font-size: inherit !important;
    line-height: inherit !important;
  }
  .what3words-autosuggest-error-wrapper {
    z-index: inherit !important;
  }
  .what3words-autosuggest-error {
    top: 0px !important;
    border: 0px !important;
    background: #555 !important;
  }
  .what3words-autosuggest-message {
    padding: 0px !important;
    color: inherit !important;
    font-size: inherit !important;
    line-height: inherit !important;
  }
</style>
Copied
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 attributeerror_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 theclip_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 theautosuggest_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

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

Recommended input element attributes

Attribute Type Description
name String Standard CSS name. Example: name="what3words"
id String Standard CSS input ID. If not specified then one will be added by our component. Example: id="what3words"
class String Standard CSS class - use with the variant=inherit attribute to apply this class to the input element of the component. Example: class="input-field"
value String Sets the initial value of the input element. We recommend always including the /// before the 3 word address. Example: value="///filled.count.soap"
placeholder String Placeholder 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

Attribute Type Description
api_key String Your what3words API Key can be specified as an attribute to the component. Example: api_key="Your-API-Key"
variant String Variant 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_message String Overwrites the error message with a custom value. Example value:"You have entered an invalid address"
language String Allows you to add a preferred suggestion fallback language. Only used when input value language cannot be determined. Example: language="EN"
autosuggest_focus String Comma 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_results Number The number of AutoSuggest results to apply the focus to. Example: n_focus_results="2"
clip_to_country String Restrict suggestions to a given country or comma separated list of countries. Example: clip_to_country="GB,US"
clip_to_bounding_box String Restrict suggestions to a bounding box specified using co-ordinates. Example: clip_to_bounding_box="51.521,-0.343,52.6,2.3324"
clip_to_circle String Restrict 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_polygon String Restrict 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_coordinates Boolean Makes 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

Event Description
value_changed Fired when the value entered into the input changes
value_valid Fired when a valid 3 word address has been selected from the suggestions
value_invalid Fires when input value is not a valid 3 word address
selected_suggestion Fires when a suggestion is selected from the dropdown.
suggestions_changed Fires when the suggestions displayed in the dropdown change
coordinates_changed Only 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.

Version Date Details
4.0.0 25/05/2021 Improved support for inheriting styling
4.0.1 08/06/2021 Bug fix release
4.0.3 16/09/2021 Update packages
Website Add a 3 word address input field GoDaddy JavaScript React SquareSpace Vue Wix WordPress

Related tutorials