Configuration object for
Customise how you wish to present freeform address search suggestions in the select box
Converts an address object into a sugestion string presented to user
API Key associated with your account. Typically begins
autocomplete= attribute of the input element. Setting this attribute aims to prevent some browsers (particularly Chrome) from providing a clashing autofill overlay.
The best practice for this attribute breaks over time (see https://stackoverflow.com/questions/15738259/disabling-chrome-autofill) and is specific to different forms. If you are observing chrome's autofill clashing on your form, update this attribute to the best practice du jour.
Target API hostname. Defaults to
An optional CSS selector or HTMLSelectElement which designates a custom button provided by you.
CSS class to attached to button element.
ID of button element.
Label attached to button.
style attribute of button
true to check if key is usable - will not initialise if set to true and key not usable
If enabled, the plugin will check if the key is in a usable state before initialising itself. The check can fail if:
If the check fails, the plugin will not initialise. Use the
onFailedCheck callback handle a failed check scenario
DOM context in which to inject Postcode Lookup tools
style attribute of postcode lookup container
The search button is temporarily disabled upon a click to prevent double presses.
cooloff attribute sets the number of milliseconds to wait before the search button is active
0 to disable altogether
Specify the Document to operate on
String map specifying default headers
Hide a list of HTML elements when Postcode Lookup is instantiated
Specify these elements using query selectors or direct HTMLElement references
An optional CSS selector which designates a custom input field provided by you.
Aria Label provided to input field. Identifies to a visually impaired user how to operate postcode lookup.
CSS class to attached to input element.
ID of input element.
style attribute of postcode input
Maximum number of addresses to present in select menu following an address search.
Only applies if strictlyPostcodes is
If strict postcode matching is set to
false, it's possible to pull down a larger set of address matches. This limit contrains the number of address results that can be presented to the user
An optional CSS selector which designates where the message container element should be inserted.
Custom message containers are not initially hidden, though they are later unhidden by setting
style.display to ""
. To hide your message container, apply style.display = "none"
orstyle="display: none;"` to your container element.
CSS class to attached to message container element
ID of message container element.
style attribute of message container
Error message presented when a freeform address search takes place and no matches are found.
Message shown when button is temporarily disabled due to lookup.
Error message presented when an unknown error occurs
Error message presented if invalid postcode.
Default message shown at top of
Message shown to user to unhide address fields if
hide attribute is configured.
Invoked when address results are applied to input fields
Invoked when user has clicked an address in select menu
Invokwed when a lookup succeeds with a list of addresses
Invoked when a user click search button
Callback invoked when API Key is enabled and check fails
Invoked when plugin is initialised
Invoked when user clicks the button to trigger a lookup
removeAll is invoked
Invoked when a search succeeds, E.g. Server responds that Postcode is found or doesn't exist
Invoked when a request succeeds but the API returns an error code
Invoked when the address select field is inserted to DOM
Invoked when the address selection select input is removed (following new search)
Invoked when any fields hidden by
hide are unhidden. Ensure this callback is idempotent as it can be triggered more than once during both hidden and unhidden states
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 HTMLInputElement
When an address is select, the addressing data will be piped to those address inputs designated in
outputFields. For instance
line_1: "#line_1" will write Address Line One data to a HTML entity with ID
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
outputFields 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.
For more sophistated behaviour when a user selects an address, you can hook into the
onAddressSelected callback and implement customised behaviour there.
Output fields assigned with a query selector are evaluated lazily (i.e. when an address attribute needs to be piped to a field).
Specify parent element for output fields to looking for them to narrow search area.
Default placeholder message in input field. Inserted as
placeholder attribute of
county from being populated if set to
organisation_name from being populated if set to
Customise how you wish to present postcode lookup address suggestions in the select box
Converts an address object into a sugestion string presented to user
Organisation name forms part of the address. Set this to
true to strip the address line results of organisation name.
Note that this may not be a good idea in a small number of scenarios as some "Large User" addresses consist of just an organisation name, post town and postcode.
Scopes the operable area of the DOM
Aria Label provided to select input. Directs a visually impaired user to select another address on the list.
CSS class to attached
<select> input field.
An optional CSS selector or HTML Element which designates where the address results
<select> element should be inserted.
The default select container is hidden using
display: none; and unhidden by setting display to
"". A custom
selectContainer will not have
display: none; initially applied but it will be unhidden by setting display to
"". To hide your
selectContainer to also be initially hidden apply
style.display = "none" or
style="display: none;" to your container element.
Class of the select container.
ID of the select container.
Designates ID of
<select> element which presents address suggestions.
If set to
true, the premise will be immediately populated if the result set of an address or postcode search contains a single premise.
Note the address selection box will not appear.
onAddressSelected callback is still invoked in this instance. To detect whether the last address search yielded a single premise, the controller instance data property will have a single element. i.e.
this.data.length === 1.
style attribute of address select
A function to test whether a lookup should be performed at all
Force autocomplete authorisation via HTTP headers only. Defaults to
Requires user to enter postcode only.
If set to false, the search term will be searched as a complete address rather than a postcode. So searches such as
SW1A 2AA 10 are possible.
Optional tags to append to helper requests
Default time in ms before HTTP request timeout. Defaults to 10s (
Title case the post town (
true) or keep in all caps (
false). All caps post town is recommended by Royal Mail's good addressing guidelines
Use TLS. Defaults to
Specify a clickable element to unhide elements hidden with
Class of clickable unhide element.
API version. Defaults to