Interface ControllerOptions

Configuration options for an Address Finder instance

interface ControllerOptions {
    agent?: Agent;
    alignToInput?: boolean;
    apiKey: string;
    aria?: "1.0" | "1.1";
    autocomplete?: string;
    baseUrl?: string;
    checkKey?: boolean;
    containerClass?: string;
    containerStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>;
    contexts?: Record<string, ContextDetails>;
    countryToggleClass?: string;
    defaultCountry?: string;
    detectCountry?: boolean;
    document?: Document;
    fixed?: boolean;
    format?: AddressFormat;
    header?: StringMap;
    hide?: (string | HTMLElement)[];
    hideToolbar?: boolean;
    injectStyle?: string | boolean;
    inputField?: SelectorNode;
    inputStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>;
    labels?: Partial<
        Record<
            | "id"
            | "dataset"
            | "country"
            | "language"
            | "line_1"
            | "line_2"
            | "county"
            | "country_iso"
            | "country_iso_2"
            | "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,
        >,
    >;
    listClass?: string;
    listStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>;
    liStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>;
    mainClass?: string;
    mainStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>;
    messageClass?: string;
    msgCountryToggle?: string;
    msgFallback?: string;
    msgInitial?: string;
    msgList?: string;
    msgNoMatch?: string;
    msgPlaceholder?: string;
    msgPlaceholderCountry?: string;
    msgUnhide?: string;
    names?: Partial<
        Record<
            | "id"
            | "dataset"
            | "country"
            | "language"
            | "line_1"
            | "line_2"
            | "county"
            | "country_iso"
            | "country_iso_2"
            | "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,
        >,
    >;
    offset?: number;
    onAddressPopulated?: OnAddressPopulated;
    onAddressRetrieved?: OnAddressRetrieved;
    onAddressSelected?: OnAddressSelected;
    onBlur?: OnBlur;
    onClose?: OnClose;
    onContextChange?: OnContextChange;
    onCountrySelected?: OnCountrySelected;
    onFailedCheck?: OnFailedCheck;
    onFocus?: OnFocus;
    onInput?: OnInput;
    onKeyDown?: OnKeyDown;
    onLoaded?: OnLoaded;
    onMounted?: OnMounted;
    onMouseDown?: OnMouseDown;
    onOpen?: OnOpen;
    onRemove?: OnRemove;
    onSearchError?: OnSearchError;
    onSelect?: OnSelect;
    onSuggestionError?: OnSuggestionError;
    onSuggestionsRetrieved?: OnSuggestionsRetrieved;
    onUnhide?: OnUnhide;
    outputFields?: Partial<
        Record<
            | "id"
            | "dataset"
            | "country"
            | "language"
            | "line_1"
            | "line_2"
            | "county"
            | "country_iso"
            | "country_iso_2"
            | "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,
        >,
    >;
    outputScope?: string
    | Document
    | HTMLElement
    | null;
    populateCounty?: boolean;
    populateOrganisation?: boolean;
    queryOptions?: QueryOptions;
    removeOrganisation?: boolean;
    resolveOptions?: ResolveOptions;
    restrictCountries?: string[];
    scope?: string | Document | HTMLElement;
    strictAuthorisation?: boolean;
    tags?: string[];
    timeout?: number;
    titleizePostTown?: boolean;
    tls?: boolean;
    toolbarClass?: string;
    unhide?: string | HTMLElement | null;
    unhideClass?: string;
    unhideStyle?: Partial<Record<keyof CSSStyleDeclaration, string>>;
    version?: string;
}

Hierarchy

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

Index

Properties

agent? alignToInput? apiKey aria? autocomplete? baseUrl? checkKey? containerClass? containerStyle? contexts? countryToggleClass? defaultCountry? detectCountry? document? fixed? format? header? hide? hideToolbar? injectStyle? inputField? inputStyle? labels? listClass? listStyle? liStyle? mainClass? mainStyle? messageClass? msgCountryToggle? msgFallback? msgInitial? msgList? msgNoMatch? msgPlaceholder? msgPlaceholderCountry? msgUnhide? names? offset? onAddressPopulated? onAddressRetrieved? onAddressSelected? onBlur? onClose? onContextChange? onCountrySelected? onFailedCheck? onFocus? onInput? onKeyDown? onLoaded? onMounted? onMouseDown? onOpen? onRemove? onSearchError? onSelect? onSuggestionError? onSuggestionsRetrieved? onUnhide? outputFields? outputScope? populateCounty? populateOrganisation? queryOptions? removeOrganisation? resolveOptions? restrictCountries? scope? strictAuthorisation? tags? timeout? titleizePostTown? tls? toolbarClass? unhide? unhideClass? unhideStyle? version?

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<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, ContextDetails>

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

Default Country

Default

"GBR"

`Optional`detectCountry

detectCountry?: boolean

Detects country based on IP address.

Default

true

`Optional`document

document?: Document

Specify the Document to operate on

Default

window.document

`Optional`fixed

fixed?: boolean

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

Default

false

`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<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`listClass

listClass?: string

CSS class assigned to suggestion list

Defaults to "idpc_ul"

Default

"idpc_ul"

`Optional`listStyle

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

Default

{}

Example

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

`Optional`liStyle

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

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

Default

{}

Example

{
  liStyle: {
    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<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

`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`onContextChange

onContextChange?: OnContextChange

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

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

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`resolveOptions

resolveOptions?: ResolveOptions

Optional configuration object to apply to address resolve queries

`Optional`restrictCountries

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

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

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

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`unhideStyle

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

Applies additional styling to the unhide element. Accepts CSSStyleDeclaration object

Default

{}

Example

{
  unhideStyle: {
    color: "#0066cc",
    cursor: "pointer",
  },
}

`Optional`version

version?: string

API version

Default

"v1"

Interface ControllerOptions

Hierarchy

Index

Properties

Properties

Optionalagent

OptionalalignToInput

Default

apiKey

Optionalaria

Optionalautocomplete

Default

OptionalbaseUrl

Default

OptionalcheckKey

OptionalcontainerClass

Default

OptionalcontainerStyle

Default

Example

Optionalcontexts

OptionalcountryToggleClass

Default

OptionaldefaultCountry

Default

OptionaldetectCountry

Default

Optionaldocument

Default

Optionalfixed

Default

Optionalformat

Default

Optionalheader

Default

Optionalhide

Default

OptionalhideToolbar

Default

OptionalinjectStyle

OptionalinputField

OptionalinputStyle

Default

Example

Optionallabels

OptionallistClass

Default

OptionallistStyle

Default

Example

OptionalliStyle

Default

Example

OptionalmainClass

Default

OptionalmainStyle

Default

Example

OptionalmessageClass

Default

OptionalmsgCountryToggle

OptionalmsgFallback

OptionalmsgInitial

OptionalmsgList

Default

OptionalmsgNoMatch

OptionalmsgPlaceholder

OptionalmsgPlaceholderCountry

OptionalmsgUnhide

Default

Optionalnames

Optionaloffset

Default

OptionalonAddressPopulated

OptionalonAddressRetrieved

OptionalonAddressSelected

OptionalonBlur

OptionalonClose

OptionalonContextChange

OptionalonCountrySelected

`Optional`agent

`Optional`alignToInput

`Optional`aria

`Optional`autocomplete

`Optional`baseUrl

`Optional`checkKey

`Optional`containerClass

`Optional`containerStyle

`Optional`contexts

`Optional`countryToggleClass

`Optional`defaultCountry

`Optional`detectCountry

`Optional`document

`Optional`fixed

`Optional`format

`Optional`header

`Optional`hide

`Optional`hideToolbar

`Optional`injectStyle

`Optional`inputField

`Optional`inputStyle

`Optional`labels

`Optional`listClass

`Optional`listStyle

`Optional`liStyle

`Optional`mainClass

`Optional`mainStyle

`Optional`messageClass

`Optional`msgCountryToggle

`Optional`msgFallback

`Optional`msgInitial

`Optional`msgList

`Optional`msgNoMatch

`Optional`msgPlaceholder

`Optional`msgPlaceholderCountry

`Optional`msgUnhide

`Optional`names

`Optional`offset

`Optional`onAddressPopulated

`Optional`onAddressRetrieved

`Optional`onAddressSelected

`Optional`onBlur

`Optional`onClose

`Optional`onContextChange

`Optional`onCountrySelected

`Optional`onFailedCheck

`Optional`onFocus

`Optional`onInput

`Optional`onKeyDown

`Optional`onLoaded

`Optional`onMounted

`Optional`onMouseDown

`Optional`onOpen

`Optional`onRemove

`Optional`onSearchError

`Optional`onSelect

`Optional`onSuggestionError

`Optional`onSuggestionsRetrieved

`Optional`onUnhide

`Optional`outputFields

`Optional`outputScope

`Optional`populateCounty

`Optional`populateOrganisation

`Optional`queryOptions

`Optional`removeOrganisation

`Optional`resolveOptions

`Optional`restrictCountries

`Optional`scope

`Optional`strictAuthorisation

`Optional`tags

`Optional`timeout

`Optional`titleizePostTown

`Optional`tls

`Optional`toolbarClass

`Optional`unhide

`Optional`unhideClass

`Optional`unhideStyle

`Optional`version