All tutorials
Using the Notes Component
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
andlabel
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>
Step by Step
Add 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.
<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>
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>
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;
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>
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, label
and 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>
“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>
“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>
Localise 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">
Configure 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>
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>
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>
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>
Streamlining 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;
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.
Attributes Table
Component script parameters
Property | Attribute | Type | Description |
---|---|---|---|
apikey | api-key | String | An API key is required for the component to function correctly. Example: <code>api-key=Your-API-Key</code> |
apiVersion | api-version | ApiVersion.Version1 | The API version to use for the what3words API requests. Example: <code>'v3' as import('@what3words/api').ApiVersion</code> |
baseUrl | base-url | String | The component can be used with an Enterprise Suite API Server instance by using baseUrl. Example: <code>baseUrl=https://example.com/v3</code> |
callback | callback | String | Allows 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> |
headers | headers | String | Enterprise API Server only - Allows for custom headers to be passed through in requests. |
Recommended textarea or 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" |
placeholder | String | Placeholder text to display. We recommend keeping the placeholder as a what3words address proceeded with "e.g." Example: placeholder="e.g ///filled.count.soap" |
Slots
Slot | Description |
---|---|
"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
Property | Attribute | Type | Description |
---|---|---|---|
addressFormat | address-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" |
apiKey | api-key | String | Your what3words API Key can be specified as an attribute to the component. Example: api-key="Your-API-Key" |
clipToBoundingBox | 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" |
clipToCircle | 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" |
clipToCountry | clip-to-country | String | Restrict suggestions to a given country or comma separated list of countries. Example: clip-to-country="GB,US" |
clipToPolygon | 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" |
language | language | String | Allows you to add a preferred suggestion fallback language. Only used when input value language cannot be determined. Example: language="EN" |
nFocusResults | n-focus-results | Number | The number of AutoSuggest results to apply the focus to. Example: n-focus-results="2" |
searchFocus | search-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" |
showHintsTooltip | show-hints-tooltip | Boolean | Show the what3words hints tooltip when clicking on the what3words status icon. Example: show-hints-tooltip="true" |
typeaheadDelay | typeahead-delay | Number | The delay in milliseconds to wait after the user has finished typing before making an autosuggest request. Example: typeahead-delay="300" |
Events Table
Event | Description |
---|---|
apiError | Emitted when an error occurs with the what3words API |
suggestionsHover | Emitted when a suggestion is hovered over |
suggestionsChanged | Emitted when the list of suggestions changes |
suggestionSelected | Emitted when a suggestion is selected |
valueChanged | Emitted when the input value changes |
valueInvalid | Emitted when the input value is not a valid what3words address |
valueValid | Emitted 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 }); });
Troubleshooting
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.