Widget headless
Headless widget
Embed the Address Validation iO widget on a headless Shopify storefront so signed-in customers can fix order addresses and get address-book checks.
The headless widget is a small script for Shopify stores with their own storefront, for example Hydrogen or Next.js. On your account pages, signed-in customers see which orders need an address check and fix them right there. It can also check addresses in your address book forms before they are saved.
The widget does not cover checkout: Address Validation iO's checkout checks run in Shopify's own checkout. A regular Shopify theme doesn't need the widget.
Before you start
- The Address Validation iO Shopify app is installed.
- Your plan includes the Headless widget package. See Pricing and Plans.
- In the app, go to Settings → Customer accounts & headless → Set up the headless widget and:
- Generate secret. It is shown only once. Store it on your storefront's server as
AVIO_WIDGET_SECRET. Never put it in browser code. - Add your storefront under Allowed origins, one per line, for example
https://shop.example.com(at most 10).http://works only forlocalhost. - Turn on the widget.
- Generate secret. It is shown only once. Store it on your storefront's server as
Every widget needs a token that your server signs for the signed-in customer. See Tokens.
Add the script
Add the script once, for example in your layout:
<script src="https://widget.address-validation.io/widget/v1/avio.js" async></script>The script mounts every element with a data-avio-widget attribute, including elements added later by client-side navigation. When data-token or data-order-id changes on an element, the widget remounts with the new values.
Widget modes
Set the mode with data-avio-widget.
orders: account overview
A notice such as "Your order #1234 needs your attention", with a list of the affected orders. It renders nothing when no order needs attention.
<div data-avio-widget="orders" data-token="CUSTOMER_TOKEN" data-order-url="/account/orders/{id}"></div>data-order-url is the link to your own order page. Keep {id} as written: the widget fills in the order id. It must be a relative or http(s) URL.
order: order details
Place it on your order page. The customer sees the current address and hints, and can choose Use this address for a suggestion, Edit your address or My address is correct. A saved change updates the order's shipping address, checks it again and releases Address Validation iO's fulfillment hold. Changes are no longer possible once the order is fulfilled or in progress.
<div data-avio-widget="order" data-order-id="ORDER_ID" data-token="ORDER_TOKEN"></div>data-order-id is the numeric Shopify order id or its gid://shopify/Order/… GID. Use an order-scoped token for this element. If Address Validation iO never checked the order, the element stays empty.
address-form: address book
Attach the widget to your own address form. When the customer saves:
- a valid address is saved right away;
- an address that needs a look shows suggestions (Use this address fills the fields and submits) or lets the customer keep their address;
- an invalid address shows the issue and blocks the save, with Use my address anyway unless the country's mode is strict.
If the check isn't possible (network error, timeout, limit reached, expired token), the form is saved as entered. The widget is guidance, not enforcement: if you must enforce valid addresses, check again on your server before saving.
<form id="address-form">…</form>
<div
data-avio-widget="address-form"
data-token="CUSTOMER_TOKEN"
data-avio-form="#address-form"
data-field-map='{"address1":"street","zip":"postalCode"}'
></div>data-avio-form: a CSS selector for the form. Without it, the widget uses the<form>around the element, or the one inside it.data-field-map: JSON that maps Address Validation iO's field names to your form's input names. The defaults areaddress1,address2,city,zip,province,provinceCode,countryCode(orcountry),firstName,lastName,companyandphone.
A form without a street, a city or a two-letter country code isn't checked and saves normally, so a missing mapping never blocks the form.
Address-book checks are not orders: they aren't billed per check and appear in your Logs as "Address form". They are limited to 20 provider checks per customer per hour.
Attributes
| Attribute | On | Meaning |
|---|---|---|
data-avio-widget |
element | orders, order or address-form |
data-token |
element or script | The signed token. A data-token on the script tag is the default for every element. |
data-order-id |
order |
The Shopify order id |
data-order-url |
orders |
Link to your order page, with {id} as placeholder |
data-avio-form |
address-form |
CSS selector of the form |
data-field-map |
address-form |
JSON map of field names |
data-locale |
element | Language of the texts, for example de. Defaults to <html lang>, then the browser's language. |
data-manual |
script | Turns off automatic mounting; call AvioWidget.mount() yourself. |
Events
Both events bubble, so you can listen on the element or on document.
| Event | Fired on | detail |
|---|---|---|
avio:order-updated |
the order element |
The updated order, after the customer saved a correction or confirmed the address. |
avio:address-result |
the form (address-form) |
The check's result, or { decision: "skipped", error } when the check failed (error is the HTTP status, 0 for a network error). |
Use avio:order-updated to refresh the parts of your page that show the order's address or status:
document.addEventListener("avio:order-updated", (event) => {
const order = (event as CustomEvent).detail;
console.log("Address updated", order);
// e.g. router.refresh() in Next.js
});JavaScript API
The script defines window.AvioWidget:
| Function | What it does |
|---|---|
mount(element) |
Mounts one element (with data-manual, or after you add it). |
scan() |
Mounts every [data-avio-widget] element on the page. |
attachAddressForm(form, { token, fieldMap?, host?, locale? }) |
Same as the address-form mode, from code. Returns { detach() }. host is where the result panel renders. |
validateAddress(address, { token, locale? }) |
Only the check, for frameworks that manage forms themselves. Returns a promise with the result (decision is valid, warn, invalid or skipped); it rejects with error.status on HTTP and network errors. |
const { detach } = window.AvioWidget.attachAddressForm(formElement, {
token,
fieldMap: { address1: "street" },
});
const result = await window.AvioWidget.validateAddress(address, { token });Look and texts
The widget renders in a Shadow DOM, so your page styles don't leak in. It uses the Design settings in the app (banner tones, suggestions, accent color) and your order-status texts in every language you turned on. To override the look, set CSS custom properties on the widget element:
| Property | Controls |
|---|---|
--avio-accent |
Buttons and accent color |
--avio-accent-text |
Text on the accent color |
--avio-accent-ink |
Accent-colored text and the focus outline |
--avio-radius |
Corner radius |
--avio-border |
Border color |
--avio-info-background, --avio-warning-background, --avio-critical-background |
Background per tone (also -color and -dot) |
When the widget shows nothing, the element gets the data-avio-empty attribute and is hidden.
Troubleshooting
The widget shows nothing
The widget is off, no secret was generated, the app was uninstalled or the package is missing. It also stays empty when no order needs attention, or when Address Validation iO never checked the order.
"Your session has expired. Please reload the page."
The token expired or the secret was rotated. Reloading the page gets a new token from your server.
The browser blocks the request
Your site isn't in Allowed origins, or it uses http:// instead of https://.