AV Elements
Last updated
Last updated
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_*
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:
Sandbox:
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
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.
The Address Verification script has many attributes to give you complete control over its appearance and behavior. They generally go by the following pattern:
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
These attributes modify the behavior of AV Elements
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-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.
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 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 3 demo
Similarly, the AV elements script is also placed in public/index.html before the closing body tag.
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 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.
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:
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.
| data-lob-*-id | data-lob-*-value |
|---|---|
| Attribute name | Attribute value(s) |
|---|---|
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"
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
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
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.
