Developer

All tutorials

Using the Notes Component

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, Vue.js and Angular.

The what3words Notes Component allows users to input a 3-word address in the delivery notes field alongside free text. It provides real-time suggestions and validation, ensuring accurate address input. By default, it uses the what3words API but can be configured to use a private instance.

This tutorial guides you through adding the JavaScript Notes Component to your website, whether you have static pages or use npm. It also covers customisation options to refine the 3-word address suggestions and how to style the component to match your site’s design.

If you aim to integrate the what3words Public API into your Node.js or browser-based applications, our JavaScript API Wrapper is ideal. You can also access the JavaScript API Wrapper via the window object using our JavaScript SDK.

Quickstart

The Notes Component requires just a few lines of code to be added to a form to create a what3words-powered textarea field.

Note:

  • Replace YOUR-API-KEY with your actual what3words API key.
  • Customise the placeholder and label text as needed.

Integrate within a Textarea Field

To add the what3words Notes Component to a textarea field in your checkout page, e.g. Delivery Notes, use the following code snippet:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Checkout Page</title>
  <script type="module" defer
    src="https://cdn.what3words.com/javascript-components@4.9.1/dist/what3words/what3words.esm.js"></script>
  <script nomodule defer
    src="https://cdn.what3words.com/javascript-components@4.9.1/dist/what3words/what3words.js"></script>
</head>
<body>
  <form id="form" method="GET">
    <!-- Add what3words notes component to the textarea field -->
    <what3words-notes api-key="YOUR-API-KEY">
      <label slot="label" for="delivery-notes" class="label">Delivery Instructions</label>
      <textarea 
         slot="input" 
         name="delivery-notes" 
         id="delivery-notes" 
         rows="10" 
         autocomplete="off"
         placeholder="Type delivery instructions with your what3words address">
      </textarea>
    </what3words-notes>
  </form>
</body>
</html>
Copied

Step by Step

1Get API key
2Add the UI 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 could add the what3words API key as a parameter to what3words.js the script but we recommend adding the API key as an attribute to the component element instead.

Alternatively, if you are using NPM for your site, you can utilise one of our packages for your framework.

<script type="module" async src="https://cdn.what3words.com/javascript-components@4.9.1/dist/what3words/what3words.esm.js"></script>
<script nomodule async src="https://cdn.what3words.com/javascript-components@4.9.1/dist/what3words/what3words.js"></script>
Copied

Versioning

The Notes Component is versioned to allow for updates and bug fixes. When installing using HTML, we recommend using a fixed version for development versions of your integrations. This will ensure a predictable version of the component is loaded, such as @4.9.1. A log of versions can be found here.

<script type="module" async src="https://cdn.what3words.com/javascript-components@4.9.1/dist/what3words/what3words.esm.js"></script>
<script nomodule async src="https://cdn.what3words.com/javascript-components@4.9.1/dist/what3words/what3words.js"></script>
Copied

When using NPM, you will also need to add an import statement for our package. Additionally, you can wrap our component around the textarea or input element as shown in the following example:

import { useState } from "react";
import { What3wordsNotes } from '@what3words/react-components';

function MyFormElement() {
  const [value, setValue] = useState("");
  const onChange = (e) => setValue(e.target.value);
  return (
      <!-- Add what3words notes component to the textarea field -->
      <What3wordsNotes apiKey="API_KEY">
        <textarea
          slot="input"
        />
      </What3wordsNotes>
  );
}

export default MyFormElement;
Copied

Configuring for use with Self-hosted API

If you run our Enterprise Suite API Server yourself, you may specify the URL to your server by appending the baseUrl parameter to the script loaded. Using the frameworks you can specify the baseUrl using window.what3words.api.setOptions.

Although we recommend adding the base_url parameter within the Notes Component container.

<script type="module" async src="https://cdn.what3words.com/javascript-components@4.9.0/dist/what3words/what3words.esm.js"></script>
<script nomodule async src="https://cdn.what3words.com/javascript-components@4.9.0/dist/what3words/what3words.js?baseUrl=https://example.com/v3"></script>
Copied

Using Slots with the what3words Notes Component

The what3words Notes Component enhances textarea or input elements, allowing users to enter both free text and what3words addresses. It provides real-time suggestions and validation for what3words addresses, ensuring accurate and efficient input. To implement this, wrap your textarea or input field with the Notes Component and specify your what3words API key as an attribute in the Notes Component container. Replace YOUR_API_KEY with your actual what3words API key.

Slots are placeholders inside web components that allow you to define where certain elements should be inserted. The what3words Notes Component uses slots to let you customise various parts of the component, such as the input field, labeland tooltip. Here we will explain what slots are and how to use them effectively.

Note: It is recommended to add a label, placeholder, and make the field optional, especially when integrating it as part of an input field for a checkout page.

“input” Slot

  • Description: The “input” slot is used for the textarea element where users can type and get suggestions.
  • Usage: Insert a textarea element inside the Notes Component and assign it to the “input” slot.
<!-- Add what3words notes component to the textarea field -->
<what3words-notes api-key="YOUR-API-KEY">
  <textarea 
    slot="input" 
    name="delivery-notes"        
    id="delivery-notes" 
    row=10 
    autocomplete="off"
    placeholder="Type delivery instructions with your what3words address">
  </textarea>  
</what3words-notes>
Copied

“label” Slot

  • Description: The “label” slot is used for the label element associated with the textarea field.
  • Usage: Insert a label element inside the Notes Component and assign it to the “label” slot.
<what3words-notes api-key="YOUR-API-KEY">
  <label slot="label" for="delivery-notes">Delivery Notes</label>
  <textarea slot="input" name="delivery-notes"></textarea>
</what3words-notes>
Copied

“tooltip” Slot

  • Description: The “tooltip” slot is used for the content displayed when clicking the status icon.
  • Usage: Insert a div element inside the Notes Component and assign it to the “tooltip” slot. You can customise the tooltip content as needed.
<what3words-notes api-key="YOUR-API-KEY">
  <label slot="label" for="delivery-notes">Delivery Notes</label>
  <textarea slot="input" name="delivery-notes"></textarea>
  <div slot="tooltip">
    <h1>Custom title</h1>
    <p>Custom content</p>
  </div>
</what3words-notes>
Copied
3Localise the Component

Supported languages

The Notes 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
4Configure Advanced Options

Controlling the what3words Display Format

The addressFormat property is a flexible way to control how what3words addresses are displayed within the Notes Component. By setting the address-format attribute to either "slashes" (e.g. ///filled.count.soap) or "url" (e.g. https://w3w.co/filled.count.soap), you can choose the format that best suits your application’s needs. The default values is the "slashes".

Here is an example to display the what3words address in the "url" format:

<what3words-notes api-key="YOUR_API_KEY" address-format="url">
  <label slot="label" for="delivery-notes">Delivery Notes</label>
  <textarea slot="input" name="delivery-notes"></textarea>
</what3words-notes>
Copied

Country clipping

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 as comma-separated.

<what3words-notes api-key="YOUR-API-KEY" clip-to-country="GB">
  <label slot="label" for="delivery-notes">Delivery Notes</label>
  <textarea slot="input" name="delivery-notes"></textarea>
</what3words-notes>
Copied

Focus

In addition to country clipping, it is also possible to add focus to results using the search-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-notes api-key="YOUR-API-KEY" search-focus="51.1,2.0">
  <label slot="label" for="delivery-notes">Delivery Notes</label>
  <textarea slot="input" name="delivery-notes"></textarea>
</what3words-notes>
Copied

Controlling Tooltip Display

The showHintsTooltip property of the what3words Notes Component allows you to control whether the what3words hint tooltip is displayed when the status icon is clicked.

By setting the show-hints-tooltip attribute to true or false, you can choose whether to display the tooltip based on your application’s requirements.

Here is an example where you decided to hide the tooltip by setting show-hints-tooltip attribute to "false".

<what3words-notes api-key="YOUR-API-KEY" show-hints-tooltip="false">
  <label slot="label" for="delivery-notes">Delivery Notes</label>
  <textarea slot="input" name="delivery-notes"></textarea>
</what3words-notes>
Copied
5Streamlining Delivery and Data Extraction

1. Ensuring Smooth Deliveries:

For flawless fulfilment, getting the identified what3words address into the hands of everyone involved is crucial. This includes integrating it with your order management system and carrier partners. By doing so, you ensure addresses are processed accurately, leading to efficient deliveries.

2. Extracting what3words Addresses:

Need to isolate what3words addresses from your existing order data? We’ve got you covered! Utilise the provided RegEx formula (included below with a cautionary note). This code helps detect potential what3words addresses within your data.

Have further questions or require assistance?

Feel free to contact our technology partner team at technology.partnerships@what3words.com. We’re happy to help you navigate what3words integration and ensure a smooth user experience.

var regex = /[^0-9`~!@#$%^&*()+\-_=[{\]}\\|'<,.>?/";:£§º©®\s]{1,}[.｡。･・︒។։။۔።।][^0-9`~!@#$%^&*()+\-_=[{\]}\\|'<,.>?/";:£§º©®\s]{1,}[.｡。･・︒។։။۔።।][^0-9`~!@#$%^&*()+\-_=[{\]}\\|'<,.>?/";:£§º©®\s]{1,}/ig;
Copied

Important Considerations:

  • While this approach simplifies integration, it’s crucial to note that the RegEx only validates the format, not the actual validity of the what3words address. Further verification might be necessary.
  • Additionally, the current implementation has limitations with Vietnamese (VI) due to the presence of spaces within Vietnamese words, which can disrupt pattern matching.

For more information on this RegEx and its variations, please refer to this tutorial.

By implementing these steps, you can leverage the power of what3words to streamline your deliveries and extract valuable location data from your existing system.

6Attributes Table

Component script parameters

PropertyAttributeTypeDescription
apikeyapi-keyStringAn API key is required for the component to function correctly. Example: <code>api-key=Your-API-Key</code>
apiVersionapi-versionApiVersion.Version1The API version to use for the what3words API requests. Example: <code>'v3' as import('@what3words/api').ApiVersion</code>
baseUrlbase-urlStringThe component can be used with an Enterprise Suite API Server instance by using baseUrl. Example: <code>baseUrl=https://example.com/v3</code>
callbackcallbackStringAllows for a callback to be fired once the component has loaded. This should be the function name to be fired. Example: <code>callback=initMap</code>
headersheadersStringEnterprise API Server only - Allows for custom headers to be passed through in requests.

Recommended textarea or 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"
placeholderStringPlaceholder text to display. We recommend keeping the placeholder as a what3words address proceeded with "e.g." Example: placeholder="e.g ///filled.count.soap"

Slots

SlotDescription
"input"The textarea element to get suggestions from when typing. Example: textarea slot="input".
"label"The label element for the input slot element. Example: label slot="label"
"tooltip"The tooltip content to display when the status icon is clicked. Example div slot="tooltip

Component attributes

PropertyAttributeTypeDescription
addressFormataddress-format"slashes" | "url"The format to display the what3words address in - slashes - e.g. ///filled.count.soap (default) - url - e.g. https://w3w.co/filled.count.soap. Example: address-format="url"
apiKeyapi-keyStringYour what3words API Key can be specified as an attribute to the component. Example: api-key="Your-API-Key"
clipToBoundingBoxclip-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"
clipToCircleclip-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"
clipToCountryclip-to-countryStringRestrict suggestions to a given country or comma separated list of countries. Example: clip-to-country="GB,US"
clipToPolygon 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"
languagelanguageStringAllows you to add a preferred suggestion fallback language. Only used when input value language cannot be determined. Example: language="EN"
nFocusResultsn-focus-resultsNumberThe number of AutoSuggest results to apply the focus to. Example: n-focus-results="2"
searchFocussearch-focus{number},${number}The focus point to prioritise results around. If not provided, the user's current location is used. Example: search-focus="51.5,-020"
showHintsTooltipshow-hints-tooltipBooleanShow the what3words hints tooltip when clicking on the what3words status icon. Example: show-hints-tooltip="true"
typeaheadDelaytypeahead-delayNumberThe delay in milliseconds to wait after the user has finished typing before making an autosuggest request. Example: typeahead-delay="300"
7Events Table
EventDescription
apiErrorEmitted when an error occurs with the what3words API
suggestionsHoverEmitted when a suggestion is hovered over
suggestionsChangedEmitted when the list of suggestions changes
suggestionSelectedEmitted when a suggestion is selected
valueChangedEmitted when the input value changes
valueInvalidEmitted when the input value is not a valid what3words address
valueValidEmitted when the input value is a valid what3words address

Listening for events

Using an event listener, it is possible to fire other functionality in a site when something changes in the Notes Component. For example, it is possible to listen for when a valid what3words 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.

document.addEventListener('DOMContentLoaded', () => {
  const notesComponent = document.querySelector('what3words-notes');

  notesComponent.addEventListener('suggestionSelected', (event) => {
    const selectedSuggestion = event.detail.suggestion;
    console.log('Suggestion selected:', selectedSuggestion);
    // You can add additional code here to handle the selected suggestion
  });
});
Copied
8Troubleshooting

Vite Compatibility Issue

Our current components do not yet work with Vite due to a known issue with Stencil. A potential fix is expected in a future version upgrade, which we are currently working on. It may take some time before this fix is available and tested. For now, we advise against using Vite. For more details, refer to the GitHub issue.

WebsiteAdd a 3 word address input fieldAngularJavaScriptReactVue

Related tutorials