Autocomplete Javascript library

A small Javascript library to integrate international address autocompletion into any HTML form.

• Zero dependencies, compatible with any Javascript framework
• Small filesize (< 4kb minified, gzipped)
• Supports IE11, Edge, Firefox, Chrome, Safari, Android, iOS

Try it out in the autocomplete example form.

Example implementation

The following example code can be used as a starting point for your implementation.

<form>
	<input type="text" class="input-autocomplete" placeholder="City, street or postcode">
</form>

const inputElement = document.querySelector('.input-autocomplete'),
	autocomplete = new PostcodeNl.AutocompleteAddress(inputElement, {
		autocompleteUrl: 'https://your-proxy-script-autocomplete-url', // Required
		addressDetailsUrl: 'https://your-proxy-script-details-url', // Required
		// Specify more options here...
	});

inputElement.addEventListener('autocomplete-select', function (e) {
	console.log('Selected item:', e.detail);
});

Address selection

When a full address is selected from the autocomplete menu, call the getDetails method and use the result to populate form fields and show the address. Example:

<form class="autocomplete-example-form">
	<input type="text" class="input-autocomplete" placeholder="City, street or postcode">
	<input type="hidden" name="country">
	<input type="hidden" name="locality">
	<input type="hidden" name="postcode">
	<input type="hidden" name="street">
	<input type="hidden" name="building">
</form>

<address class="autocomplete-result"></address>

const inputElement = document.querySelector('.input-autocomplete'),
	resultElement = document.querySelector('.autocomplete-result'),
	form = document.querySelector('.autocomplete-example-form'),
	autocomplete = new PostcodeNl.AutocompleteAddress(inputElement, {
		// Options
	});

inputElement.addEventListener('autocomplete-select', function (e) {
	if (e.detail.precision === 'Address')
	{
		autocomplete.getDetails(e.detail.context, function (result) {
			const fields = ['country', 'locality', 'postcode', 'street', 'building'];

			for (let i = 0, field; field = fields[i++];)
			{
				form.elements[field].value = result.address[field];
			}

			if (typeof result.mailLines !== 'undefined')
			{
				// Show the address.
				resultElement.innerHTML = result.mailLines.join('<br>');
			}
		});
	}
});

Setting defaults

The default value of each option can be set via the defaults object. Any autocomplete instance will then use the new default value.

// Set default URL values:
PostcodeNl.AutocompleteAddress.defaults.autocompleteUrl = 'https://autocomplete-url';
PostcodeNl.AutocompleteAddress.defaults.addressDetailsUrl = 'https://details-url';

Options

context: string

Initial autocomplete context. E.g. a country code "nld", "bel" or "deu" to start searching in that country. Default: "nld"

autocompleteUrl: string

URL that will return autocomplete JSON data. Default: undefined

addressDetailsUrl: string

URL that will return address details JSON data. Default: undefined

tags: Object

Text to use with tags. Default:

{
	'unvalidated-housenumber': '(unknown house number)',
	'unvalidated-housenumber-addition': '(unknown house number addition)',
}

cssPrefix: string

Prefix for CSS classnames. Default: "postcodenl-autocomplete-"

minLength: number

Minimum number of characters typed before a search is performed. Default: 1

delay: number

Delay in milliseconds between when a keystroke occurs and when a search is performed. Not applied when input length is 1-3 characters in order to provide immediate feedback when a user starts typing. Default: 300

appendTo: string|HTMLElement

Which element the menu should be appended to. Default: document.body

autoFocus: boolean

Focus the first item when the menu is shown. Default: true

autoSelectSingleAddress: boolean

Automatically select an address match if it's the only menu item. Requires the autoFocus option to be enabled or won't have any effect. Default: true

autoResize: boolean

Automatically calculate menu width. Disable to define width in CSS. Default: true

getResponseMessage: Function

Get screen reader text for a successful response with at least one match. Override this function to translate the message. Default:

function (count, languageTag)
{
	let message;

	if (count > 1)
	{
		message = count + ' address suggestions available. ';
	}
	else
	{
		message = 'One address suggestion available. ';
	}

	message += 'Use up and down arrow keys to navigate.';

	return message;
}

language: string

The language used for API calls. If defined, is added to the request for autocomplete suggestions. Default: undefined

buildingListMode: string

Determines how building suggestions are presented, for example when in a Street context. Allowed values are: 'short', 'paged'. The default is 'short', to present only the first few buildings. We recommend using 'paged', this allows more buildings suggestions and gives the user the option to browse through available buildings. Default: "short"

Properties

version: string

Holds the autocomplete library version string.

Example

PostcodeNl.AutocompleteAddress.version; // "1.4.1"

Methods

setCountry(iso3Code)

Set the country to start searching in.

iso3Code: string

ISO 3166-1 alpha-3 country code.

search(element, term, context) or search(element, options)

Trigger a search on the specified input element. If invoked without a term, the current input's value is used.

element: HTMLElement

Input element associated with the autocomplete instance.

term: string

Search query, optional.

context: string

Autocomplete context, optional.

options: Object

Autocomplete options object, optional. Use this in place of the term parameter to specify named options. All its properties are optional.

term: string

Search query.

context: string

Autocomplete context.

showMenu: boolean

Whether the menu should be shown. Set to false to perform a "hidden" search (useful with prefilled input values).

Example

// Perform a search without showing the menu:
autocompleteInstance.search(inputElement, { term: 'test', showMenu: false });

xhrGet(url, success) → {XMLHttpRequest}

Create an XMLHttpRequest GET request.

url: string

URL to which the request is sent.

success: Function

Function that is executed if the request succeeds.

Returns: XMLHttpRequest

Object representing the eventual completion/failure of the request, and its resulting value.

getSuggestions(context, term, response) → {XMLHttpRequest}

Get autocomplete matches for the specified context and term.

context: string

A place identifier denoting the context to search in. e.g. “nld”.

term: string

The search query to process. e.g. “2012ES”, “Haarlem”, “Julian”.

response: Function

Function that handles the response.

Returns: XMLHttpRequest

Object representing the eventual completion/failure of the request, and its resulting value.

getDetails(addressId, [dispatchCountry], response) → {XMLHttpRequest}

Get address details for the specified address identifier.

addressId: string

Address identifier returned by a match of precision “Address”.

dispatchCountry (optional): string

Dispatching country ISO3 code, used to determine country address line presence and language. If not given, country is not added in mailLines.

response: Function

Function that handles the response.

Returns: XMLHttpRequest

Object representing the eventual completion/failure of the request, and its resulting value.

renderItem(ul, item) → {HTMLElement}

Method that controls the creation of each menu item.

ul: HTMLElement

Element that the newly created list item must be appended to.

item: Object

Single autocomplete item.

Returns: HTMLElement

List item element containing an autocomplete match.

highlight(str, indices) → {string}

Highlight matched portions in the item label.

str: string

Item label to highlight.

indices: Array.Array.<number>

Array of character offset pairs.

Returns: string

Highlighted string (using <mark> elements).

announce(str)

Announce screen reader text via the live region.

str: string

Text to announce.

destroy()

Removes autocomplete functionality from associated input elements.

reset()

Reset to initial context, clear the menu, clear input values.

setLanguage(languageTag)

Set the language used for API calls.

languageTag: string

Language tag, e.g. "nl", "nl_NL", "en-GB" or "de-DE".

Events

autocomplete-create

Triggered when the autocomplete is created.

Example

inputElement.addEventListener('autocomplete-create', function () {});
const autocomplete = new PostcodeNl.AutocompleteAddress(inputElement, { /* Options */ });
// autocomplete-create event triggered.

autocomplete-open

Triggered when the menu is opened.

Example

inputElement.addEventListener('autocomplete-open', function () {});

autocomplete-close

Triggered when the menu is closed.

Example

inputElement.addEventListener('autocomplete-close', function () {});

autocomplete-focus

Triggered when focus is moved to an item by keyboard (not selecting). The default action is to replace the input element's value with the value of the focused item. Cancel this event to prevent updating the input element's value.

Example

inputElement.addEventListener('autocomplete-focus', function (e) {
	e.preventDefault(); // Event cancelled, input value won't be updated.
});

autocomplete-select

Triggered when an item is selected from the menu. Selected item data is available on the detail property of the Event object. Cancel this event to prevent updating the input element's value.

Example

inputElement.addEventListener('autocomplete-select', function (e) {
	console.log('Selected item:', e.detail);
	e.preventDefault(); // Event cancelled, input value won't be updated.
});

autocomplete-search

Triggered before a search is performed. Cancel this event to prevent the request for address suggestions.

Example

inputElement.addEventListener('autocomplete-search', function (e) {
	e.preventDefault(); // Event cancelled, no request made.
});

autocomplete-response

Triggered after a search completes, before the menu is shown. Result data is available via the detail property of the Event object. Cancel this event to prevent rendering address suggestions.

Example

inputElement.addEventListener('autocomplete-response', function (e) {
	console.log('Address suggestions:', e.detail.matches);
	e.preventDefault(); // Event cancelled, no items added to the menu.
});

autocomplete-error

Triggered when the request for autocomplete suggestions fails.

Example

inputElement.addEventListener('autocomplete-error', function (e) {
	console.log('ProgressEvent:', e.detail.event);
	console.log('XMLHttpRequest:', e.detail.request);
});