ControllerConfig | @ideal-postcodes/postcode-lookup

Configuration object for Controller

Hierarchy

Config
Omit<ClientConfig, "api_key">
- ControllerConfig

Index

Properties

Optional addressSearchFormatter

addressSearchFormatter: GbrAddressFormatter

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

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 associated with your account. Typically begins ak_

required

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 button

button: null | string | HTMLButtonElement

An optional CSS selector or HTMLSelectElement which designates a custom button provided by you.

example: "#my_custom_button"

Optional buttonClass

buttonClass: null | string

CSS class to attached to button element.

default: "idpc-button"

Optional buttonId

buttonId: null | string

ID of button element.

default: null

Optional buttonLabel

buttonLabel: string

Label attached to button.

default: "Find my GbrAddress"

Optional buttonStyle

buttonStyle: Partial<Record<keyof CSSStyleDeclaration, string>>

Assign style attribute of button

default: {}

Optional checkKey

checkKey: boolean

Set to 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:

Your key has no remaining lookups
Your key has run into its lookup limit for the day
Your key is requested from a URL which is not on your whitelist
The user seeking to use the key has exceeded their limit for the day

If the check fails, the plugin will not initialise. Use the onFailedCheck callback handle a failed check scenario

context

context: string | HTMLElement

DOM context in which to inject Postcode Lookup tools

required

Optional contextStyle

contextStyle: Partial<Record<keyof CSSStyleDeclaration, string>>

Assign style attribute of postcode lookup container

default: {}

Optional cooloff

cooloff: number

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

Set to 0 to disable altogether

default: 500

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 input

input: null | string | HTMLInputElement

An optional CSS selector which designates a custom input field provided by you.

example: "#my_custom_input"

Optional inputAriaLabel

inputAriaLabel: string

Aria Label provided to input field. Identifies to a visually impaired user how to operate postcode lookup.

default: "Search a postcode to retrieve your address"

Optional inputClass

inputClass: null | string

CSS class to attached to input element.

default: "idpc-input"

Optional inputId

inputId: null | string

ID of input element.

default: null

Optional inputStyle

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

Assign style attribute of postcode input

default: {}

Optional limit

limit: number

Maximum number of addresses to present in select menu following an address search.

Only applies if strictlyPostcodes is false.

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

default: 10

Optional message

message: null | string | HTMLParagraphElement

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.

example: "#my_custom_msg_container"

Optional messageClass

messageClass: null | string

CSS class to attached to message container element

default: "idpc-error"

Optional messageId

messageId: null | string

ID of message container element.

default: null

Optional messageStyle

messageStyle: Partial<Record<keyof CSSStyleDeclaration, string>>

Assign style attribute of message container

default: {}

Optional msgAddressNotFound

msgAddressNotFound: string

Error message presented when a freeform address search takes place and no matches are found.

default: "We could not find a match for your address. Please type in your address"

Optional msgDisabled

msgDisabled: string

Message shown when button is temporarily disabled due to lookup.

default: "Finding addresses..."

Optional msgError

msgError: string

Error message presented when an unknown error occurs

default: "Sorry, we weren't able to get the address you were looking for. Please type in your address"

Optional msgNotFound

msgNotFound: string

Error message presented if invalid postcode.

default: "Your postcode could not be found. Please type in your address"

Optional msgSelect

msgSelect: string

Default message shown at top of <select> menu.

default: "Please select your address"

Optional msgUnhide

msgUnhide: string

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

default: "Enter address manually"

Optional onAddressPopulated

onAddressPopulated: OnAddressPopulated

Invoked when address results are applied to input fields

Optional onAddressSelected

onAddressSelected: OnAddressSelected

Invoked when user has clicked an address in select menu

Optional onAddressesRetrieved

onAddressesRetrieved: OnAddressesRetrieved

Invokwed when a lookup succeeds with a list of addresses

Optional onButtonTrigger

onButtonTrigger: OnButtonTrigger

Invoked when a user click search button

Optional onFailedCheck

onFailedCheck: OnFailedCheck

Callback invoked when API Key is enabled and check fails

Optional onLoaded

onLoaded: OnLoaded

Invoked when plugin is initialised

Optional onLookupTriggered

onLookupTriggered: OnLookupTriggered

Invoked when user clicks the button to trigger a lookup

Optional onRemove

onRemove: OnRemove

Invoked when removeAll is invoked

Optional onSearchCompleted

onSearchCompleted: OnSearchCompleted

Invoked when a search succeeds, E.g. Server responds that Postcode is found or doesn't exist

Optional onSearchError

onSearchError: OnSearchError

Invoked when a request succeeds but the API returns an error code

Optional onSelectCreated

onSelectCreated: OnSelectCreated

Invoked when the address select field is inserted to DOM

Optional onSelectRemoved

onSelectRemoved: OnSelectRemoved

Invoked when the address selection select input is removed (following new search)

Optional onUnhide

onUnhide: OnUnhide

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

Optional outputFields

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 GbrAddress Line One data to a HTML entity with ID line_1.

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

More information on addressing data can be found on our data documentation.

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

default

{}

example

{
  line_1: "#line_1",
  line_2: "#line_2",
  line_3: "#line_3",
  post_town: document.getElementById("post_town"),
  postcode: document.getElementById("postcode")
}

Optional outputScope

outputScope: null | string | HTMLElement | Document

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

Optional placeholder

placeholder: string

Default placeholder message in input field. Inserted as placeholder attribute of input element.

default: "Search your postcode"

Optional populateCounty

populateCounty: boolean

Suppresses county from being populated if set to false

default: true

Optional postcodeSearchFormatter

postcodeSearchFormatter: GbrAddressFormatter

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

Optional removeOrganisation

removeOrganisation: boolean

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.

default: false

Optional scope

scope: string | HTMLElement | Document

Scopes the operable area of the DOM

default: window.document

Optional selectAriaLabel

selectAriaLabel: null | string

Aria Label provided to select input. Directs a visually impaired user to select another address on the list.

default: "Select your address"

Optional selectClass

selectClass: null | string

CSS class to attached <select> input field.

default: "idpc-select"

Optional selectContainer

selectContainer: null | string | HTMLDivElement

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.

example: "#my_custom_select_container"
example: document.querySelector("#my_custom_select_container");

Optional selectContainerClass

selectContainerClass: null | string

Class of the select container.

default: "idpc-select-container"

Optional selectContainerId

selectContainerId: null | string

ID of the select container.

default: null

Optional selectId

selectId: null | string

Designates ID of <select> element which presents address suggestions.

default: null

Optional selectSinglePremise

selectSinglePremise: boolean

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.

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

Defaults to false.

default: false

Optional selectStyle

selectStyle: Partial<Record<keyof CSSStyleDeclaration, string>>

Assign style attribute of address select

default: {}

Optional shouldLookupTrigger

shouldLookupTrigger: ShouldLookupTrigger

A function to test whether a lookup should be performed at all

Optional strictAuthorisation

strictAuthorisation: boolean

Force autocomplete authorisation via HTTP headers only

default: false

Optional strictlyPostcodes

strictlyPostcodes: boolean

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

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

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

default: 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: null | string

Class of clickable unhide element.

default: "idpc-unhide"

Optional version

version: string

API version

default: "v1"