Find and autocomplete addresses with Address Finder
![Dependency Status](https://david-dm.org/ideal-postcodes/address-finder.svg)
![install size](https://packagephobia.now.sh/badge?p=@ideal-postcodes/address-finder)
@ideal-postcodes/address-finder
is a Javascript library that delivers address autocomplete (or adress typeahead) search functionality on a webpage.
Address Finder is the fastest way to integrate address completion on a web page.
In depth client documentation can be found at address-finder.ideal-postcodes.dev.
@ideal-postcodes/address-finder
should be consumed by a bundler or transpiler (e.g. webpack, parcel, rollup) for minification, module resolution and specific browser support.
Targets IE11 and above. For older browser support please see our legacy ideal-postcodes-autocomplete.
address-finder-bundled provides pre-bundled versions of address-finder
, which can be immediately dropped into a page.
Links
Related Projects
How it Works
![Browser Testing](https://img.ideal-postcodes.co.uk/address-finder.gif)
- Add the library to your page. Your page should have pre-existing address input fields as well as an input field to host the finder
- Run initialisation code providing a reference to a parent container 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
- When an address is selected with the mouse, keyboard or touch, your address fields are populated with the correct address attributes
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"),
},
});
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 output_fields
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 onAddressSelected
callback and implement customised behaviour there.
Styling
The Address Finder's default CSS stylesheet can be found in the css/
directory of this repository.
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
CSS selector or HTML Element which specifies the <input>
field which the Address Finder interface should bind
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
API Key from your Ideal Postcodes account. Typically begins ak_
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 an address suggestion or full 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.
License
GNU Affero General Public License v3.0