ControllerOptions | @ideal-postcodes/address-finder

Configuration options for an Address Finder instance

Hierarchy

Partial<Callbacks>
- 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

Optional alignToInput

alignToInput: boolean

Automatically aligns address finder

default: true

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"

default: "idpc_autocomplete"

Optional containerStyle

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

default

{}

example

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

Optional contexts

contexts: Record<string, Details>

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

Optional countryToggleClass

countryToggleClass: string

CSS class assigned to country toggle button

default: "idpc_country"

Optional defaultCountry

defaultCountry: Context

Default Country

default: "GBR"

Optional document

document: Document

Specify the Document to operate on

default: window.document

Optional format

format: AddressFormat

Specify the format to receive the resolved address in.

default: "gbr"

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 hideToolbar

hideToolbar: boolean

Hides the toolbar. Users are unable to change the country

default: false

Optional injectStyle

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

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

Defaults to "idpc_ul"

default: "idpc_ul"

Optional listStyle

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

default

{}

example

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

Optional mainClass

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"

default: "idpc_af"

Optional mainStyle

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

default

{}

example

{
  mainStyle: {
    backgroundColor: "#000",
  },
}

Optional messageClass

messageClass: string

CSS class assigned to message box

Defaults to "idpc_error"

default: "idpc_error"

Optional msgCountryToggle

msgCountryToggle: string

Aria-label attached to country select bytton

Defaults to "Click to change your country"

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"

default: "Select your address"

Optional msgNoMatch

msgNoMatch: string

Message presented when no matches found for a particular query

Defaults to "No matches found"

Optional msgPlaceholder

msgPlaceholder: string

Message in input placeholder when address results are suggested

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

Optional msgPlaceholderCountry

msgPlaceholderCountry: string

Message in input placeholder when country suggestions are presented

Defaults to "Select your country"

Optional msgUnhide

msgUnhide: string

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

default: "Enter address manually"

Optional names

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 offset

offset: number

Offset of AddressFinder from input in pixels

default: 2

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 onCountrySelected

onCountrySelected: OnCountrySelected

Invoked when a user selects a country.

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 on input field occurs

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 mouse click on Address suggestion occuers

Optional onOpen

onOpen: OnOpen

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

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

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 | Document | HTMLElement

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 queryOptions

queryOptions: QueryOptions

Optional configuration object to apply to address queries

Optional removeOrganisation

removeOrganisation: boolean

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

This is false by default.

Optional restrictCountries

restrictCountries: Context[]

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

default: []

Optional scope

scope: string | Document | HTMLElement

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 toolbarClass

toolbarClass: string

CSS class assigned to toolbar at bottom of Address Finder

default: "idpc_toolbar"

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"