Customising Address Auto-Complete

This page shows you how to adjust the behaviour of Address Auto-Complete. There are a range of settings and callbacks you can use.

Click here to find out how to add Address Auto-Complete to multiple forms on the same page.

Layout Options

The code itself supports two different layouts via CSS.

The interface can be placed underneath the search field (default):

new clickToAddress({
    /*core code
    ...
    */
    gfxMode: 1
});

Or it can surround the field:

new clickToAddress({
    /*core code
    ...
    */
    gfxMode: 2
});

Styling Options

There are a number of built-in styling options to easily make the interface dark or light, and to change the highlighted text to one of our pre-defined styles.

Examples:

new clickToAddress({
    /*core code
    ...
    */
    style: {
        ambient: "dark",
        accent: "deepOrange"
    }
});

new clickToAddress({
    /*core code
    ...
    */
    style: {
        ambient: "light",
        accent: "default"
    }
});

• Note: The style object will expect both the ambient and accent property to be defined.
• For the full list of available styles, check out our API Documentation.
• If you want to go beyond the built-in styles, you can take a look at our CSS structure on GitHub. You can either include an extra css file to override our styling, or add the cssPath parameter to pass in a URL for your own CSS, instead of using the default CDN url.

Restricting the Country List

By default, all available countries are shown. To limit usage to a smaller subset of countries, you can pass in an array of countries in the configuration.

For example, you can limit the enabled countries by ISO 3166 Alpha-2 (2 letter) or ISO 3166 Alpha-3 (3 letter) country codes:

new clickToAddress({
    /*core code
    ...
    */
    countryMatchWith: "iso\_2",
    enabledCountries: ["pl", "hu", "uk"]
});

Or by naming the countries in full:

new clickToAddress({
    /*core code
    ...
    */
    countryMatchWith: "text",
    enabledCountries: ["Poland", "Hungary", "United Kingdom"]
});

• The countryMatchWith parameter tells the JavaScript class how to match the enabledCountries list against the full list of available countries. You can set it to iso_2, iso_3 (default) or text. While iso_2 and iso_3 restricts the search to exact ISO 3166 country short codes, text searches in all known names in the country list.
• Note: If you choose the text option, always type in the full name of the country to avoid partial matches.
• List of ISO 3166 Alpha-2 and Alpha-3 country codes

Area Exclusions

The excludeAreas option prevents certain regions from showing in the search results. For example, some merchants may want to exclude Jersey and Guernsey addresses from United Kingdom searches. The accepted values are shown in the snippet below.

new clickToAddress({
    /*core code
    ...
    */
    excludeAreas: [
        'gbr_northern_ireland',
        'gbr_isle_of_man',
        'gbr_isle_of_wight',
        'gbr_channel_islands',
        'gbr_all_except_northern_ireland',
        'usa_non_contiguous',
        'usa_insular_areas',
        'usa_armed_forces'
    ]
});

Click here for more information.

Events and Triggers

If you need to further process the data you receive from the API or if you need to trigger events on certain user actions, you can attach functions to be called by the JavaScript class.

Event: onResultSelected

This event is triggered after an address has been selected.

The sample below shows you how to trigger custom code to let jQuery know the country field has changed after the user selects an address:

new clickToAddress({
    /*core code
    ..
    */
    onResultSelected: function(c2a, elements, address){
        //do something useful, like trigger the country change event
        jQuery(elements.country).trigger('change');
    }
});

The method to call the other two functions is exactly the same for the other two options.

• Sometimes it’s necessary to trigger a browser event (for example, a change event on the country dropdown) if you have a code that would do something based on that user action. Most e-commerce solutions have dynamic form validation triggering on such events, and might prevent the user from advancing to the next stage of checkout unless these events are triggered.
• There are always 3 parameters passed in to these functions:
  1. the first object is the address lookup javascript object itself
  2. the second object is the object that contains the passed in dom elements
  3. the third object contains all the details to the selected address
• It is possible to configure the JavaScript class with just the search element defined. Use onResultSelected to retrieve all the address details via JavaScript.

Event: onCountyChange (States and Counties)

This event’s main purpose is to provide a way to trigger custom code instead of executing the default county / state matching algorithm. By default, the JavaScript applies a fuzzy matching algorithm, that tries to find the most similar county / state name in your dropdown (if required).

However, there might be some cases when matching this way is just not efficient or viable. For example, custom translated county lists or if the way of storing the county / state requires a JavaScript action.

If you set this event, the county won’t be set by our code. Only the supplied custom code will be executed.

Complete Code Example

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx',
    dom: {
        search:     'search-bar',
        town:       'address-town',
        postcode:   'address-zip',
        line_1:     'address-line-1',
        line_2:     'address-line-2',
        country:    'address-country'
    },
    domMode: 'id',
    style: {
        ambient: 'dark',
        accent: 'default'
    },
    gfxMode: 2,
    countryMatchWith: 'iso\_3',
    enabledCountries: ['GBR','SWE','AUS'],
    onResultSelected: function(c2a, elements, address){
        console.log("Congratulations, You just picked an address!");
    },
    onCountyChange: function(c2a, elements, address){
        console.log("County Changed");
    }
});