API Docs Postman Template Gallery
Contact Us

AV Elements

How to get started

Registration

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

Usage

Address Elements works by targeting the input elements of your address form and using their values with Lob's verification and autocomplete functionality. Include the AV Elements script tag immediately before the closing <body> tag

Code demo:

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

Sandbox:

Shopify users

AV elements works great with e-commerce platforms because they use predictable element names. For example, Shopify users can simply paste the following preconfigured script at the bottom of their Shopify Plus template.

Remember to replace live_pub_xxx with your Lob public key

<script src="https://cdn.lob.com/lob-address-elements/2.2.1/lob-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>

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 (lob-address-elements.min.merged.js). This ensures all dependencies are included in the download.

Attribute reference cheatsheet

The Address Verification script has many attributes to give you complete control over its appearance and behavior. They generally go by the following pattern:

data-lob-*-iddata-lob-*-value

These attributes are used to identify an element on your web page. Their values should be the elements ID and correspond to the components of an address: primary line, secondary line, city, state, and zip.

Example: data-lob-primary-id="address1"

These attributes modify the behavior of autocomplete and verification. Their values are either true, false, or a string from a list of options

Example: data-lob-verify-value="passthrough"

Form detection attributes

With version 2, AV Elements can detect address form inputs automatically. We can improve performance by skipping the form detection process when these attributes are provided. Set them to the IDs for each field to target.

  • data-lob-primary-id

  • data-lob-secondary-id

  • data-lob-city-id

  • data-lob-state-id

  • data-lob-zip-id

  • data-lob-country-id

Form functionality attributes

These attributes modify the behavior of AV Elements

Attribute nameAttribute value(s)

data-lob-verify-value

  • strict

  • normal

  • relaxed

  • passthrough

  • false

Controls the strictness level when verifying an address. If the strictness criteria is not met, we block the form submission and prompt the user to correct the address. Set to passthrough to submit the form regardless of the verification result. Set to false to disable verification altogether.

Default: relaxed

Learn more about Lob's strictness setting‍

data-lob-primary-value

Enables or disables address autocompletion.

Default: true

data-lob-secondary-value

When set to false, force the suite or unit number to render on the primary address line during address verification.

Default: true

Custom error handling

data-lob-*-message-id Identifies the element containing the error message at the input level. Lob will update the text content for this element and toggle its display.

  • data-lob-primary-message-id

  • data-lob-secondary-message-id

  • data-lob-city-message-id

  • data-lob-city-message-id

  • data-lob-zip-message-id

  • data-lob-country-message-id

Example: data-lob-primary-message-id points to the element below the input for Address 1. Any errors related to the primary line will be inserted inside this element.

data-lob-err-*-value Overrides the default error message when a value is missing or specific Lob verification error messages

  • data-lob-err-primary-line-value

  • data-lob-err-city-state-zip-value

  • data-lob-err-zip-value

  • data-lob-err-undeliverable-value

  • data-lob-err-missing-unit-value

  • data-lob-err-unnecessary-unit-value

  • data-lob-err-incorrect-unit-value

  • data-lob-err-confirm-value

  • data-lob-err-default-value

data-lob-anchor-id This optional attribute will place the general error message before the element with the id provided. An alternative attribute is data-lob-anchor-class which will search for the target element by class name.

Usage with React & Vue

Modern web frameworks like React and Vue boost developer productivity without sacrificing control. Add IDs to the components of your address inputs (they will be included in the compiled HTML at runtime) then include these IDs in the form detection attributes of the AV elements script.

If your component has many layers, you must ensure that the ID is propagated down to the root html components being used.

React example

React demo

In this demo we use React out of the box and create an address form. The AV elements script is added in public/index.html before the closing body tag. This demo also overrides some styles to keep the verification message centered in the form and to undo the styles applied to our primary address by our dependency algolia (for autocompletion).

Vue example

Vue 3 demo

Similarly, the AV elements script is also placed in public/index.html before the closing body tag.

A note about component libraries

The AV elements script searches for key form elements like the form tag and <input type="submit" />. When building your form with component libraries such as Material-UI or Ant Design, check for the following:

  • An ID can be propagate down to the root html elements used by the component.

  • The components render the appropriate html elements for their behavior - they are materially honest (e.g. not styling links as buttons or using hidden elements to work correctly)

Case #1 may be the more common scenario you'll come across. If this happens, you will need to fallback to writing the component yourself in place of using the library's component.

International support

International address verification is enabled when there is a country input present and it is set outside the United States. Form detection is relaxed on international forms since different countries may require different sets of address components.

Autocomplete is disabled for international addresses.

Troubleshooting

AV Elements employs multiple strategies to detect your address form. If none of them work, we display an error message to help fix this. Those messages are shown below:

Missing or duplicate form elements

Problem: These errors arise in the form detection process:

Either we are unable to find the input for a given address component, or we detected multiple inputs that may correspond to the same address component. There could be various causes for these errors including the input not existing, a label we're not familiar with, or a problem with the component's implementation from an external library.

Solution: Add the attribute(s) mentioned in the error to the AV elements script. The value should be an element id. For example, with the message above we must add the attribute data-lob-state-id.

<script src="https://cdn.lob.com/lob-address-elements/2.2.1/lob-address-elements.min.merged.js"
data-lob-key="live_pub_xxx"
data-lob-state-id="id_of_state_input"
></script>pick
PreviousAV integrations & librariesNextShopify App: Address Cleanser

Last updated