Configuration options for an Address Finder instance


  • Partial<Callbacks>
  • Partial<Omit<Config, "api_key">>
    • ControllerOptions


agent?: Agent

HTTP Agent

For downstream clients like core-node and core-browser, this will default to the native platform HTTP client

alignToInput?: boolean

Automatically aligns address finder


apiKey: string

API Key from your Ideal Postcodes account. Typically begins ak_

aria?: "1.0" | "1.1"

Configures which WAI-ARIA specification version Address Finder should target.

  • "1.1" will target the most recent spec
  • "1.0" will enable some regressions to support the 1.0 spec.

Although 1.1 was released in 2017, this currently defaults to "1.0" as it receives the widest support among screen readers. VoiceOver (for MacOS and iOS) and NVDA in particular benefit from this.

Defaults to "1.0"

autocomplete?: string

Sets the 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 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.



baseUrl?: string

Target API domain


checkKey?: boolean

An optional field to check whether the key is usable against the Ideal Postcodes API. This should be used in conjunction with the onFailedCheck callback to specify the necessary behaviour when the API Key is not in a usable state. This is true by default.

containerClass?: string

CSS class assigned to the AddressFinder container/wrapper

Defaults to "idpc_autocomplete"



containerStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>

Applies additional styling to the the Address Finder container element. Accepts CSSStyleDeclaration object `containerStyle encapsulates all elements of Address Finder including the input, ARIA controls




containerStyle: {
backgroundColor: "#000",
contexts?: Record<string, ContextDetails>

Provide a custom list of possible contexts to select a new country or context from

countryToggleClass?: string

CSS class assigned to country toggle button



defaultCountry?: string

Default Country



detectCountry?: boolean

Detects country based on IP address.


document?: Document

Specify the Document to operate on



fixed?: boolean

Set CSS display attribute to fixed on the Address Finder list element


format?: AddressFormat

Specify the format to receive the resolved address in.


header?: StringMap

String map specifying default headers


hide?: (string | HTMLElement)[]

Hide a list of HTML elements when Postcode Lookup is instantiated

Specify these elements using query selectors or direct HTMLElement references


hideToolbar?: boolean

Hides the toolbar. Users are unable to change the country


injectStyle?: string | boolean

Inject stylesheet into DOM to style Address Finder with default theme. Default is true

Styling of the Address Finder can be achieved using a CSS file. Set this to false if you wish to do this

  • true Injects the default styles into the DOM
  • string e.g. will include a CSS Stylesheet in the DOM with the src set as the string
inputField?: SelectorNode

CSS selector or HTML Element which specifies the <input> field which the Address Finder View should bind.

inputStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>

Applies additional styling to the input field. Ideal for quick tweaks. Accepts CSSStyleDeclaration object Input styles are restored to original when controller is detached from DOM




inputStyle: {
backgroundColor: "#000",
labels?: Partial<Record<"id" | "dataset" | "language" | "line_1" | "line_2" | "county" | "country_iso" | "country_iso_2" | "country" | "line_3" | "post_town" | "postcode" | "county_code" | "uprn" | "udprn" | "umprn" | "postcode_outward" | "postcode_inward" | "dependant_locality" | "double_dependant_locality" | "thoroughfare" | "dependant_thoroughfare" | "building_number" | "building_name" | "sub_building_name" | "po_box" | "department_name" | "organisation_name" | "postcode_type" | "su_organisation_indicator" | "delivery_point_suffix" | "premise" | "administrative_county" | "postal_county" | "traditional_county" | "district" | "ward" | "longitude" | "latitude" | "eastings" | "northings", string>>

An object specifying the labels associated with HTML Input Elements to target for address population

liStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>

Applies additional styling to the the Address Finder list element. Accepts CSSStyleDeclaration object




liStyle: {
backgroundColor: "#000",
listClass?: string

CSS class assigned to suggestion list

Defaults to "idpc_ul"



listStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>

Applies additional styling to the the suggestion list. Accepts CSSStyleDeclaration object

style encapsulates all visible elements of Address Finder. This element is actively shown/hidden when AddressFinder is toggled




listStyle: {
backgroundColor: "#000",
mainClass?: string

CSS class assigned to Address Finder element. This element is the main visible element containing address suggestions, messages and toolbar underneath the address finder

Defaults to "idpc_af"



mainStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>

Applies additional styling to the the Address Finder Main Component. The Main Component contains the visible elements of the Address Finder such as the address suggestion list, toolbar and messages which appears underneath the input field.

Accepts CSSStyleDeclaration object




mainStyle: {
backgroundColor: "#000",
messageClass?: string

CSS class assigned to message box

Defaults to "idpc_error"



msgCountryToggle?: string

Aria-label attached to country select bytton

Defaults to "Click to change your country"

msgFallback?: string

Fallback message in case communication message with API fails

Defaults to "Please enter your address manually"

msgInitial?: string

Initial message when Address Finder opens an no query is available

Defaults to "Start typing to find address"

msgList?: string

Aria-label attached to the suggestion list. Prompts screen reader user on how to operate list

Defaults to "Select your address"


"Select your address"

msgNoMatch?: string

Message presented when no matches found for a particular query

Defaults to "No matches found"

msgPlaceholder?: string

Message in input placeholder when address results are suggested

Defaults to "Try the first line or postal code of your address"

msgPlaceholderCountry?: string

Message in input placeholder when country suggestions are presented

Defaults to "Select your country"

msgUnhide?: string

Message shown to user to unhide address fields if hide attribute is configured


"Enter address manually"
names?: Partial<Record<"id" | "dataset" | "language" | "line_1" | "line_2" | "county" | "country_iso" | "country_iso_2" | "country" | "line_3" | "post_town" | "postcode" | "county_code" | "uprn" | "udprn" | "umprn" | "postcode_outward" | "postcode_inward" | "dependant_locality" | "double_dependant_locality" | "thoroughfare" | "dependant_thoroughfare" | "building_number" | "building_name" | "sub_building_name" | "po_box" | "department_name" | "organisation_name" | "postcode_type" | "su_organisation_indicator" | "delivery_point_suffix" | "premise" | "administrative_county" | "postal_county" | "traditional_county" | "district" | "ward" | "longitude" | "latitude" | "eastings" | "northings", string>>

An object specifying the names of HTML Input Elements to target for address population

This will fallback to aria-name if a name cannot be detected

offset?: number

Offset of AddressFinder from input in pixels


onAddressPopulated?: OnAddressPopulated

Invoked when selected address is populated into address fields of user address form

onAddressRetrieved?: OnAddressRetrieved

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.

onAddressSelected?: OnAddressSelected

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.

onBlur?: OnBlur

Invoked when blur event is dispatched by Address Finder input field

onClose?: OnClose

Invoked when the Address Finder view closes (i.e. disappears)

onContextChange?: OnContextChange

Invoked each time context changed (i.e. user change country to search address)

onCountrySelected?: OnCountrySelected

Invoked when a user selects a country.

onFailedCheck?: OnFailedCheck

Invoked when checkKey is enabled and the key is discovered to be in an unusable state (e.g. daily limit reached, no balance, etc).

onFocus?: OnFocus

Invoked when focus event is dispatched by Address Finder input field

onInput?: OnInput

Invoked when input event is dispatched by Address Finder input field

onKeyDown?: OnKeyDown

Invoked when keypress on input field occurs

onLoaded?: OnLoaded

Invoked when Address Finder has been successfully attached to the input element.

onMounted?: OnMounted

Invoked when view is attached to the DOM

onMouseDown?: OnMouseDown

Invoked when mouse click on Address suggestion occuers

onOpen?: OnOpen

Invoked when Address Finder suggestion box is opened (i.e. presented to the user).

onRemove?: OnRemove

Invoked when view is detached from the DOM

onSearchError?: OnSearchError

Invoked when an error has occurred following an attempt to retrieve a full address. i.e. the API request made after the user selects a suggestion.

The first argument is an error instance (i.e. inherits from Error) representing the error which has occurred.

In this scenario the user will also receive a message to manually input an address if address retrieval fails.

onSelect?: OnSelect

Invoked when a suggestion has been selected

onSuggestionError?: OnSuggestionError

Invoked when an address suggestion retrieval request has failed.

In this scenario the user will be alerted that no address suggestions could be found and to manually input an address.

onSuggestionsRetrieved?: OnSuggestionsRetrieved

Invoked immediately after address suggestions are retrieved from the API. The first argument is an array of address suggestions.

onUnhide?: OnUnhide

Invoked when hidden fields are unhidden (i.e. user selects an address or opts for manual input)

outputFields?: Partial<Record<"id" | "dataset" | "language" | "line_1" | "line_2" | "county" | "country_iso" | "country_iso_2" | "country" | "line_3" | "post_town" | "postcode" | "county_code" | "uprn" | "udprn" | "umprn" | "postcode_outward" | "postcode_inward" | "dependant_locality" | "double_dependant_locality" | "thoroughfare" | "dependant_thoroughfare" | "building_number" | "building_name" | "sub_building_name" | "po_box" | "department_name" | "organisation_name" | "postcode_type" | "su_organisation_indicator" | "delivery_point_suffix" | "premise" | "administrative_county" | "postal_county" | "traditional_county" | "district" | "ward" | "longitude" | "latitude" | "eastings" | "northings", SelectorNode>>

An object specifying where address field data points should be piped.

The attribute of the document should be the same as the address attribute as found in the documentation. E.g. line_1, post_town, postcode.

You may use a CSS selector string or a HTMLElement. E.g. { line_1: "#line_1" } or { line_1: document.getElementById("line_1") }

Using an HTMLElement as an outputField selector has the effect of eagerly binding the Address Finder instance to your output fields. When using string selectors, Address Finder will bind to your ouput fields when when an address is selected.

outputScope?: null | string | Document | HTMLElement

Specify parent element for output fields to looking for them to narrow search area

populateCounty?: boolean

Suppresses county from being populated if set to false


populateOrganisation?: boolean

Suppresses organisation_name from being populated if set to false


queryOptions?: QueryOptions

Optional configuration object to apply to address queries

removeOrganisation?: boolean

Optional. An optional field to remove organisation name from address lines.

This is false by default.

restrictCountries?: string[]

Narrow the countries you wish to support

Setting this to an empty array (default) will enable all countries

Setting this to a single country will disable country selection and hide the country selection toolbar



scope?: string | Document | HTMLElement

Scopes the operable area of the DOM



strictAuthorisation?: boolean

Force autocomplete authorisation via HTTP headers only


tags?: string[]

Append tags to helper requests like lookupPostcode and lookupUDPRN

Tags attached to the client are overwritten on an request if it is also specified in the helper request options


timeout?: number

Default time in ms before HTTP request timeout. Defaults to 10s (10000)


titleizePostTown?: boolean

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

tls?: boolean



toolbarClass?: string

CSS class assigned to toolbar at bottom of Address Finder



unhide?: null | string | HTMLElement

Specify a clickable element to unhide elements hidden with hide


unhideClass?: string

Class of clickable unhide element


version?: string

API version