Options
All
  • Public
  • Public/Protected
  • All
Menu

Configuration options for an Address Finder instance

Hierarchy

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

Index

Properties

Optional agent

agent: Agent

HTTP Agent

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

apiKey

apiKey: string

API Key from your Ideal Postcodes account. Typically begins ak_

Optional aria

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"

Optional autocomplete

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

default

"none"

Optional baseUrl

baseUrl: string

Target API domain

default

"api.ideal-postcodes.co.uk"

Optional checkKey

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.

Optional containerClass

containerClass: string

CSS class assigned to the AddressFinder container/wrapper

Defaults to "idpc_autocomplete"

Optional containerStyle

containerStyle: Partial<Record<number | keyof CSSStyleDeclaration, string>>

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

default

{}

example
{
  containerStyle: {
    backgroundColor: "#000",
  },
}

Optional document

document: Document

Specify the Document to operate on

default

window.document

Optional header

header: StringMap

String map specifying default headers

default

{}

Optional hide

hide: (string | HTMLElement)[]

Hide a list of HTML elements when Postcode Lookup is instantiated

Specify these elements using query selectors or direct HTMLElement references

default

[]

Optional injectStyle

injectStyle: string | boolean

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

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. https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder@1.1.1/css/address-finder.min.css will include a CSS Stylesheet in the DOM with the src set as the string

Optional inputField

inputField: SelectorNode

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

Optional inputStyle

inputStyle: Partial<Record<number | 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

default

{}

example
{
  inputStyle: {
    backgroundColor: "#000",
  },
}

Optional labels

labels: Partial<Record<keyof Address, string>>

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

Optional liStyle

liStyle: Partial<Record<number | keyof CSSStyleDeclaration, string>>

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

default

{}

example
{
  liStyle: {
    backgroundColor: "#000",
  },
}

Optional listClass

listClass: string

CSS class assigned to suggestion list (bound to <ul>)

Defaults to "idpc_ul"

Optional listStyle

listStyle: Partial<Record<number | keyof CSSStyleDeclaration, string>>

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

default

{}

example
{
  listStyle: {
    backgroundColor: "#000",
  },
}

Optional messageClass

messageClass: string

CSS class assigned to message box

Defaults to "idpc_error"

Note this doesn't necessarily indicate an error

Optional msgFallback

msgFallback: string

Fallback message in case communication message with API fails

Defaults to "Please enter your address manually"

Optional msgInitial

msgInitial: string

Initial message when Address Finder opens an no query is available

Defaults to "Start typing to find address"

Optional msgList

msgList: string

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

Defaults to "Select your address"

Optional msgNoMatch

msgNoMatch: string

Message presented when no matches found for a particular query

Defaults to "No matches found"

Optional msgUnhide

msgUnhide: string

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

default

"Enter address manually"

Optional names

names: Partial<Record<keyof Address, 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

Optional onAddressPopulated

onAddressPopulated: OnAddressPopulated

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

Optional onAddressRetrieved

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.

Optional onAddressSelected

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.

Optional onBlur

onBlur: OnBlur

Invoked when blur event is dispatched by Address Finder input field

Optional onClose

onClose: OnClose

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

Optional onFailedCheck

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).

Optional onFocus

onFocus: OnFocus

Invoked when focus event is dispatched by Address Finder input field

Optional onInput

onInput: OnInput

Invoked when input event is dispatched by Address Finder input field

Optional onKeyDown

onKeyDown: OnKeyDown

Invoked when keypress is triggerd on input

Optional onLoaded

onLoaded: OnLoaded

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

Optional onMounted

onMounted: OnMounted

Invoked when view is attached to the DOM

Optional onMouseDown

onMouseDown: OnMouseDown

Invoked when mousedown event is triggered on suggestion list

Optional onOpen

onOpen: OnOpen

Invoked when the Address Finder view opens (i.e. appears)

Optional onRemove

onRemove: OnRemove

Invoked when view is detached from the DOM

Optional onSearchError

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.

Optional onSelect

onSelect: OnSelect

Invoked when a suggestion has been selected

Optional onSuggestionError

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.

Optional onSuggestionsRetrieved

onSuggestionsRetrieved: OnSuggestionsRetrieved

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

Optional onUnhide

onUnhide: OnUnhide

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

Optional outputFields

outputFields: Partial<Record<keyof Address, 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.

Optional outputScope

outputScope: null | string | HTMLElement | Document

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

Optional populateCounty

populateCounty: boolean

Suppresses county from being populated if set to false

default

true

Optional populateOrganisation

populateOrganisation: boolean

Suppresses organisation_name from being populated if set to false

default

true

Optional removeOrganisation

removeOrganisation: boolean

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

This is false by default.

Optional scope

scope: string | HTMLElement | Document

Scopes the operable area of the DOM

default

window.document

Optional strictAuthorisation

strictAuthorisation: boolean

Force autocomplete authorisation via HTTP headers only

default

false

Optional tags

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

default

[]

Optional timeout

timeout: number

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

default

10000

Optional titleizePostTown

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

Optional tls

tls: boolean

Use TLS

default

true

Optional unhide

unhide: null | string | HTMLElement

Specify a clickable element to unhide elements hidden with hide

default

null

Optional unhideClass

unhideClass: string

Class of clickable unhide element

default

"idpc-unhide"

Optional version

version: string

API version

default

"v1"