/address-elements

Primary LanguageJavaScriptMIT LicenseMIT

Address Elements

The Lob Address Elements library simplifies client side integration of Lob's US Address Autocompletion and US Address Verification APIs. Use it to enrich any standard HTML page to include both autocompletion and pre-verification behaviors.

Table of Contents

Registration

Create an account at Lob.com to obtain a Live Public API Key. The key is available in the Lob Settings Panel and uses the format, live_pub_*.

Usage

Embed the Lob Address Elements script immediately before the closing <body> tag in the html containing your address form. The script will autodetect your form and its inputs.

  <script src="https://cdn.lob.com/lob/address-elements/2.2.1/address-elements.min.js"
    data-lob-key="live_pub_xxx"></script>

To view more configuration option see the cheat sheet wiki

Preconfigured Usage

E-commerce platforms like Shopify use predictable element names making them easy to extend. Paste the following preconfigured script into your top-level Shopify Plus template to add address verification to your checkout form. Remember to replace live_pub_xxx with your Lob public key.

<script src="https://cdn.lob.com/lob/address-elements/2.2.1/address-elements.min.merged.js"
  data-lob-key="live_pub_xxx"
  data-lob-verify-value="strict"
  data-lob-primary-value="false"
  data-lob-err-bgcolor="#006eff"
  data-lob-err-color="#ffffff"></script>

<!-- Here's another example that places the verification message above the submit/continue button at checkout. -->
<script src="https://cdn.lob.com/lob/address-elements/2.2.1/address-elements.min.merged.js"
  data-lob-key="live_pub_xxx"
  data-lob-verify-value="strict"
  data-lob-primary-value="false"
  data-lob-err-bgcolor="#006eff"
  data-lob-err-color="#ffffff"
  data-lob-verify-message-anchor-class="step__footer"></script>

NOTE: Many E-commerce platforms have strict content security policies that prevent scripts from loading additional content. Embed the merged build of Address Elements to handle these situations as shown in the example above (address-elements.min.merged.js). This ensures all dependencies are included in the download.

Multiform Usage

Address elements can enrich multiple address forms at the same time, within the same Web page. Each address must be contained within a different HTML <form> parent for verification to function properly.

<!DOCTYPE html>
<html>
  <body>
    <form>
      ...
    </form>

    <form>
      ...
    </form>
  </body>
</html>

React Usage

We have a React component library! Check out @lob/react-address-autocomplete for a smoother developer experience.

Address Elements assumes an address form already exists on your web page when it starts up. This is usually not the case for most React apps, so you will need to load the script after your address form is done rendering/mounting.

Using Life Cycle methods

class MyComponent extends React.Component {
  ...
  // Place this inside the component containing your address form
  componentDidMount() {
    const script = document.createElement("script");
    script.src = "https://cdn.lob.com/lob/address-elements/2.2.1/address-elements.min.js";
    script.async = true;
    script.setAttribute("data-lob-key", "live_pub_xxx");
    document.body.appendChild(script);
  }
  ...
}

Using Hooks

const MyComponent = () => {
  ...
  // Place this inside the component containing your address form
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://cdn.lob.com/lob/address-elements/2.2.1/address-elements.min.js";
    script.async = true;
    script.setAttribute("data-lob-key", "live_pub_xxx");
    document.body.appendChild(script);
  }, []);
  ...
}

Check out the React demo here

Vue Usage

We have a Vue component library too! @lob/vue-address-autocomplete has all of your Vue autocomplete needs.

Similar to React, add the script tag after your address form component has rendered.

// Place this inside the component containing your address form
export default {
  ...
  mounted() {
    const script = document.createElement("script");
    script.src = "https://cdn.lob.com/lob/address-elements/2.2.1/address-elements.min.js";
    script.async = true;
    script.setAttribute("data-lob-key", "live_pub_xxx");
    document.body.appendChild(script);
  }
  ...
}

Check out the Vue demo here

Configuration and Customization

See our Script Attribute Reference Sheet wiki for all the ways you can control the Address Elements script.

Form Detection

With v2.0.0, when a script gets added to a page we search for inputs and labels with address-related key words. Any errors that may arise are displayed in the web page and the browser's console.

In order to disable form detection you must provide the IDs to the address inputs in the AV elements script tag. Here is an example:

<script src="https://cdn.lob.com/lob/address-elements/2.2.1/address-elements.min.merged.js"
  data-lob-key="live_pub_xxx"
  data-lob-primary-id="address1"
  data-lob-secondary-id="address2"
  data-lob-city-id="city"
  data-lob-state-id="state"
  data-lob-zip-id="zip"></script>

Page Events

Address Elements publishes address-related events as the user interacts with an enriched form. These include:

  • elements.enriched | Address Form Enriched
  • elements.us_autocompletion.suggestion | US Autocompletion Suggested
  • elements.us_autocompletion.selection | US Autocompletion Selected
  • elements.us_autocompletion.error | US Autocompletion Errored
  • elements.us_verification.alert | US Verification Alerted
  • elements.us_verification.improvement | US Verification Improved
  • elements.us_verification.verification | US Verification Succeeded
  • elements.us_verification.error | US Verification Errored

Subscribe to relevant events once the Address Elements library has loaded. Use the # wildcard to subscribe to any event.

LobAddressElements.on('elements.#', function (payload, event) {
  console.log(event.topic, Object.keys(payload));
});

Unsubscribe by maintaining a reference to the subscription response. In this example, the elements.enriched event will execute only once.

const off = LobAddressElements.on('elements.enriched', function (payload, event) {
  console.log(event.topic, payload.form);
  off();
});

The target address form is returned in the event payload, providing additional context when multiple address forms are present.

Component Styles

For an in-depth guide to modifying the styles injected by Address Elements, please refer to our styling guide wiki.

International Verification

Address Elements is capable of verifying international addresses. Simply include a country input in your form to enable this feature. When the value of the input is outside the United States we automatically switch to Lob's international verification endpoint. The same form attributes are used for international verifications (e.g. data-lob-zip-id is still used for postal code, data-lob-state-id for province, etc).

Note: Autocomplete functionality is disabled for international addresses.

Examples

This repo includes several example implementations. These represent a range of HTML forms and environments that may be similar to your own.

Contributing

To contribute, please see the CONTRIBUTING.md file.

Building

The minified version of the Address Elements library is available for download from the Lob CDN. You do not need to clone the Github repo to use in your Website.

If you do decide to fork and build your own instance of Address Elements, we use webpack for minifying your source. Execute via the CLI

NOTE: Webpack will bind the minified file name to the the version number in package.json

npm run build

Latest Release

2.2.3 (CURRENT / LATEST)

Current Improvements
Removes Algolia/jQuery autocomplete dependency

See release notes for previous versions

Copyright © 2021 Lob.com

Released under the MIT License, which can be found in the repository in LICENSE.txt.