The Autocomplete Controller class acts as the public class which you may wield to enable address autocomplete on your HTML address forms

When instantiated, the controller will serve as a bridge beteen the address suggestion view presented on the DOM and the Ideal Postcodes Address resolution HTTP APIs

The role of the controller is to bind to events produced by the user interface and take appropriate action including querying the API, modifying other aspects of the DOM.


  • Controller


alerts: HTMLDivElement

Reference to alerts container

announce: Announce

Reference to accessibility announcer

blurListener: Listener<"blur">

Input blur event listener

cache: ApiCache

Address Finder API cache

client: Client

Ideal Postcodes API Client

container: HTMLDivElement

Reference to container wrapping AddressFinder elements DOM element. This includes the main component, input fields and WAI-ARIA controls

context: string

Current search context

contextSuggestions: ContextDetails[]

Current list of context suggestions

countryIcon: HTMLSpanElement

Reference to country icon

countryInput: null | HTMLInputElement | HTMLSelectElement

Reference to input DOM element

countryListener: Listener<"change">

Country form input change listener

countryMessage: HTMLSpanElement

Reference to country toggle message

countryToggle: HTMLSpanElement

Reference to country select toggle button

current: number

Index of current elem in list selected

document: Document

Reference to the DOM, to which this.scope belongs

focusListener: Listener<"focus">

Input focus event listener

fsm: ViewService

Address Finder state machine

ids: IdGen

ID generation method

input: HTMLInputElement

Reference to input DOM element

inputListener: Listener<"input">

Input element input event listener

inputStyle: null | string

Caches input style prior to Address Finder attachment

keydownListener: Listener<"keydown">

Input keydown event listener

list: HTMLUListElement

Reference to Address Suggestion list DOM element

mainComponent: HTMLDivElement

Reference to inner container wrapping list and toolbar

message: HTMLLIElement

Reference to Address Finder message DOM element

notification: string

Current notification to be shown to user

options: StoredOptions

Caches options

outputScope: Document | HTMLElement

Scopes the DOM for fields which should receive address inputs

placeholderCache: undefined | string

Caches previous placeholder value for input

retrieveSuggestions: DebouncedFunc<RetrieveSuggestions>

Debounced method used to retrieve suggestions

scope: Document | HTMLElement

Scopes the DOM for the entire controller

suggestions: AddressSuggestion[]

Current list of address suggestions

toolbar: HTMLDivElement

Reference to toolbar at bottom of finder list

unhide: HTMLElement

Reference to clickable Unhide link

unhideEvent: Listener<"click">

Unhide click event listener


  • Resolves a suggestion to full address and apply results to form


    • suggestion: AddressSuggestion

    Returns Promise<Controller>

  • Marks aria component as closed

    Returns void

  • Marks aria component as opened

    Returns void

  • Adds Address Finder to DOM

    • Wraps input with container
    • Appends suggestion list to container
    • Enables listeners
    • Starts FSM

    Returns Controller

  • Close address finder


    • reason: CloseReason = "blur"

    Returns void

  • Returs false if address finder is closed

    Returns boolean

  • Creates a clickable element that can trigger unhiding of fields

    Returns HTMLElement

  • Removes Address Finder from DOM

    • Disable listeners
    • Removes sugestion list from container
    • Appends suggestion list to container
    • Enables listeners
    • Stops FSM

    Returns Controller

  • Updates current li in list to active descendant

    Returns void

  • Hides fields marked for hiding

    Returns void

  • Attaches Controller to the DOM.

    If checkKey is enabled, a key check will be performed prioer to binding. Use the onLoaded and onFailedCheck callbacks to define follow up behaviour if the key check succeeds or fails

    Returns Promise<void>

  • Returns true if address finder is open

    Returns boolean

  • Writes a selected to the input fields specified in the controller config


    • address: AnyAddress

    Returns void

  • Returns current address query

    Returns string

  • Render available country options

    Returns void

  • Render current address suggestions

    Returns void

  • Sets message as a list item, no or empty string removes any message


    • notification: string

    Returns Controller

  • Applies new query options to search. This process clears the existing cache to prevent stale searches


    • options: QueryOptions

    Returns void

  • Applies new query options to search. This process clears the existing cache to prevent stale searches


    • options: ResolveOptions

    Returns void

  • Set address finder suggestions


    • suggestions: AddressSuggestion[]
    • query: string

    Returns Controller

  • Unhides fields marked for hiding

    Returns void

  • Removes unhide elem from DOM

    Returns void