Options
All
  • Public
  • Public/Protected
  • All
Menu

Configuration object for Controller

Hierarchy

  • Config
  • {}
    • ControllerConfig

Index

Properties

Optional addressSearchFormatter

addressSearchFormatter: AddressFormatter

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

apiKey

apiKey: string

API Key associated with your account. Typically begins ak_

required

Optional button

button: string | HTMLButtonElement | null

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

example

"#my_custom_button"

Optional buttonClass

buttonClass: string | null

CSS class to attached to button element

default

"idpc-button"

Optional buttonId

buttonId: string | null

ID of button element

default

null

Optional buttonLabel

buttonLabel: undefined | string

Label attached to button

default

"Find my Address"

Optional buttonStyle

buttonStyle: CSSStyle

Assign style attribute of button

Optional checkKey

checkKey: undefined | false | true

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: CSSStyle

Assign style attribute of postcode lookup container

Optional cooloff

cooloff: undefined | 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 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: string | HTMLInputElement | null

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

example

"#my_custom_input"

Optional inputAriaLabel

inputAriaLabel: undefined | 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: string | null

CSS class to attached to input element

default

"idpc-input"

Optional inputId

inputId: string | null

ID of input element

default

null

Optional inputStyle

inputStyle: CSSStyle

Assign style attribute of postcode input

Optional limit

limit: undefined | 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: string | HTMLParagraphElement | null

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

CSS class to attached to message container element

default

"idpc-msg"

Optional messageId

messageId: string | null

ID of message container element

default

null

Optional messageStyle

messageStyle: CSSStyle

Assign style attribute of message container

Optional msgAddressNotFound

msgAddressNotFound: undefined | 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: undefined | string

Message shown when button is temporarily disabled due to lookup

default

"Finding addresses..."

Optional msgError

msgError: undefined | 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: undefined | string

Error message presented if invalid postcode

default

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

Optional msgSelect

msgSelect: undefined | string

Default message shown at top of <select> menu

default

"Please select your address"

Optional msgUnhide

msgUnhide: undefined | 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

outputFields: 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 Address 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 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.

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: string | HTMLElement | Document | null

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

Optional placeholder

placeholder: undefined | string

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

default

"Please enter your postcode"

Optional postcodeSearchFormatter

postcodeSearchFormatter: AddressFormatter

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: undefined | false | true

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

Scopes the operable area of the DOM

default

window.document

Optional selectAriaLabel

selectAriaLabel: string | null

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

CSS class to attached <select> input field

default

"idpc-select"

Optional selectContainer

selectContainer: string | HTMLDivElement | null

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

Class of the select container

default

"idpc-select-container"

Optional selectContainerId

selectContainerId: string | null

ID of the select container

default

null

Optional selectId

selectId: string | null

Designates ID of <select> element which presents address suggestions

default

null

Optional selectSinglePremise

selectSinglePremise: undefined | false | true

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: CSSStyle

Assign style attribute of address select

Optional shouldLookupTrigger

shouldLookupTrigger: ShouldLookupTrigger

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

Optional strictlyPostcodes

strictlyPostcodes: undefined | false | true

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 titleizePostTown

titleizePostTown: undefined | false | true

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 unhide

unhide: string | HTMLElement | null

Specify a clickable element to unhide elements hidden with hide

default

null

Optional unhideClass

unhideClass: string | null

Class of clickable unhide element

default

"idpc-unhide"