Find and autocomplete addresses with Address Finder
@ideal-postcodes/address-finder
is a JavaScript library that delivers address autocomplete (or adress typeahead) search functionality on a webpage.
This package should be consumed by a bundler or transpiler (e.g. webpack, parcel, rollup) for minification, module resolution and specific browser support.
For a pre-bundled version of address-finder
(minified, transpiled, polyfilled, etc) that can immediately be dropped on a webpage, use address-finder-bundled.
Links
Example Setup
Related Projects
How it Works
- Add the library to your project. Your webpage should have pre-existing address input fields as well as an input field to host the finder
- Run initialisation code providing a reference to the Address Finder input and any other configuration
- Address Finder binds to the input field of your choice and renders a dropdown of address suggestion when the user starts typing
Documentation
Configuration & Usage
Install
Add address-finder to your project via npm
npm install @ideal-postcodes/address-finder
Instantiate
Instantiate Address Finder with AddressFinder.setup
.
import { AddressFinder } from "@ideal-postcodes/address-finder";
const controller = AddressFinder.setup({
inputField: "#line_1",
apiKey: "iddqd",
outputFields: {
line_1: "#line_1",
line_2: "#line_2",
line_3: "#line_3",
post_town: "#post_town",
postcode: "#postcode",
},
});
Configuration options
It's also possible to pass HTMLElements
as inputField
or outputFields
.
AddressFinder.setup({
inputField: document.getElementById("line_1"),
outputFields: {
line_1: document.getElementById("line_1"),
},
apiKey: "iddqd",
});
Detach
After instantiating Address Finder, it is possible to toggle availability with the .detach()
and .attach()
methods.
controller.view.detach();
controller.view.attach();
Quickstart
A complete list of quick integration examples can be found at ideal-postcodes.co.uk/address-finder-demo
Populating your Address Fields
Address Finder expects you to address inputs on the page ready to be populated.
When an address is select, the addressing data will be piped to those address inputs designated in output_fields
. For instance line_1: "#line_1"
will write Address Line One data to a HTML entity with ID line_1
.
Assigning the 3 address line, post town and postcode fields, is all addressing information required to identify a UK premise. You may extract more data for an address by passing more properties into the output_fields
configuration object.
The configuration attributes for outputFields
matches the Address response object. E.g. street name can be populated can be populated using the thoroughfare
attribute. A list of address attributes provided by the API can be found at @ideal-postcodes/api-typings.
More information on addressing data can be found on our data documentation.
For more sophistated behaviour when a user selects an address, you can hook into the onAddressRetrieved
callback and implement customised behaviour there.
Styling
The Address Finder's default CSS stylesheet can be found in the css/
directory of this repository.
The Address Finder view CSS is structured in the following way:
- The target input and Address Finder suggestion list is wrapped in a
<div>
with a default class of idpc_autocomplete
- Address Suggestions are rendered in a
<ul>
list with a default class of idpc_ul
- Any messages (including prompts to type, errors, etc) are rendered in a
<li>
with a default class of idpc_error
Default CSS classes can be overridden. For instance, containerClass, listClass and messageClass are all defined in defaults.
Set injectStyle: true
to inject default Address Finder style into DOM. Defaults to false
.
Set to a URL to retrieve a CSS stylesheet. E.g.
{
injectStyle: "https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder@1.2.1/css/address-finder.min.css",
}
Messages
Default messages (e.g. "Start typing to find address", "No matches found") can be overridden. See:
Setup Options
AddressFinder.setup()
accepts a single configuration object and returns the Address Finder controller instance.
Below is the list of parameters you can use to modify Address Finder.
A complete list of configuration options can be found in the library documentation
Required Config
CSS selector or HTML Element which specifies the <input>
field which the Address Finder interface should bind
API Key from your Ideal Postcodes account. Typically begins ak_
Specify where to send address data given a selected address. A object which maps an address attribute to the CSS selector of an input field or HTMLElement
like HTMLInputElement
or HTMLTextAreaElement
.
{
line_1: "#line_1",
line_2: "#line_2",
line_3: "input[name='line_3']",
post_town: document.getElementById("post_town"),
postcode: document.getElementById("postcode")
}
The configuration attributes for outputFields
matches the Address response object. E.g. street name can be populated can be populated using the thoroughfare
attribute. A list of address attributes provided by the API can be found at @ideal-postcodes/api-typings.
More complex, dynamic assignment can be performed using the onAddressRetrieved
callback.
Output fields assigned with a query selector are evaluated lazily (i.e. when an address attribute needs to be piped to a field).
Configure Behaviour
If enabled, the plugin will check if the key is in a usable state before initialising itself.
The check can fail if:
- Your key has no remaining lookups
- Your key has run into its lookup limit for the day
- Your key is requested from a URL which is not on your whitelist
- The user seeking to use the key has exceeded their limit for the day
If the check fails, the plugin will not initialise. You can use the onFailedCheck
callback to customise your response to a failed check.
An optional field to convert the case of the Post Town from upper case into title case. E.g. "LONDON"
becomes "London".
Default is true
If set to true
, organisation name will be removed from the address.
Note that addresses which are exclusively an organisation name will not result in the organisation name being removed as this will result in no premise identifier.
Defaults to false
.
Lifecycle Callbacks
Address Finder also provides callbacks which let you hook into specific events in the controller lifecyle.
Invoked when Address Finder has been successfully attached to the input element.
A function invoked if checkKey
is enabled and the check fails.
Invoked immediately after address suggestions are retrieved from the API. The first argument is an array of address suggestions.
Invoked immediately after the user has selected a suggestion (either by click or keypress). The first argument is an object which represents the suggestion selected.
Invoked when the Address Finder client has retrieved a full address from the API following a user accepting a suggestion. The first argument is an object representing the address that has been retrieved.
Invoked when an error has occurred following an attempt to retrieve a full address. In this scenario the user will also receive a message to manually input their address.
The first argument is an error instance (i.e. inherits from Error
) representing the error which has occurred.
Examples of errors includes "lookup balance exhausted" and "lookup limit reached" errors.
Invoked when an error has occurred following an attempt to retrieve suggestions for a key press. In this scenario the user will also receive a message to manually input their address.
The first argument is an error instance (i.e. inherits from Error
) representing the error which has occurred.
Examples of errors includes "lookup balance exhausted" and "lookup limit reached" errors.
Invoked when Address Finder suggestion box is opened (i.e. presented to the user).
Invoked when the user unfocuses from the address input field.
Invoked when Address Finder suggestion box is closed (i.e. hidden from user).
Invoked when user selects or focuses address input field.
Invoked when user selects or focuses address input field.
Invoked when an address suggestion in suggestion box is selected.
Licence
GNU Affero General Public License v3.0