Address Autocomplete JavaScript Solution

The Address Autocomplete JavaScript Solution is a lightweight JavaScript tool that makes it easy to add Smarty’s US Address Autocomplete and/or International Address Autocomplete to any web form that collects address information with minimal setup.

As users begin typing an address, the plugin displays suggested addresses in a dropdown list. When the user selects a suggestion, the plugin automatically fills in the remaining address fields.

*Note: If you’re a developer looking for full technical documentation and advanced configuration options, you can visit the npm README. This guide provides a simplified overview of the plugin.

Contents

1. Quick start
   1. Locate the form you want to enhance with the plugin.
   2. Initialize the Address Autocomplete JavaScript Solution with this short snippet.
   3. Implement the clean-up function.
2. Field definitions
   • Required options
   • Form field selectors
3. Advanced options
   • Multiple instances
   • API options
   • Themes
4. Additional considerations for international autocomplete setup
   • Set the country

Quick start

The Address Autocomplete JavaScript Solution is designed to work with almost any address form. We’ll help you get started:

1. Locate the form you want to enhance with the plugin.

   If you don’t already have a form, you can create one like the example below:

   <form>
   	<input type="text" id="street" placeholder="Start typing an address..." />
   	<input type="text" id="secondary" />
   	<input type="text" id="city" />
   	<input type="text" id="state" />
   	<input type="text" id="zipcode" />
   </form>

   Each address-related field needs to be identified with CSS selectors, such as IDs or class names. In this example, the fields use the IDs street, city, state, and zipcode.

2. Initialize the Address Autocomplete JavaScript Solution with this short JavaScript snippet.

   <script src="https://cdn.jsdelivr.net/npm/smarty-address/dist/smarty-address.iife.js">
   </script>
   
   <script type="module">
   	const autocomplete = await SmartyAddress.create({
   		embeddedKey: "your-smarty-embedded-key",
   		streetSelector: "#street",
   		secondarySelector: "#secondary",
   		citySelector: "#city",
   		stateSelector: "#state",
   		zipcodeSelector: "#zipcode",
   	});
   </script>

   *Be sure to replace the embeddedKey and selector values with your own.

   You can find or create your embedded key in your Smarty account under Account → API Keys.

   What you’re doing by initializing the plugin is allowing the fields to automatically populate when the user selects the address, such as street, city, state, and ZIP Code. If the selected address includes secondary address options such as an apartment or suite, the plugin can prompt the user to select the correct unit.

3. Implement the clean-up function.

   When you no longer need an autocomplete instance (for example, when navigating away in a single-page application), call destroy() to clean up event listeners and DOM elements to prevent memory leaks:

   const autocomplete = await SmartyAddress.create({
   	embeddedKey: "your-key",
   	streetSelector: "#street",
   });
   
   // Later, when done with the autocomplete:
   autocomplete.destroy();

Field definitions

Required options

These options are required for the Address Autocomplete JavaScript Solution to work.

Form field selectors

These selectors define where the selected address data will populate.

Advanced options

The Address Autocomplete JavaScript Solution can be customized to work with many different address form layouts. Use the required options to get started, then add optional selectors and filters to match your form layout and desired user experience.

This documentation provides a simplified overview of the most common configuration options. For a complete list of configuration settings, see our npm README.

Multiple instances

You can create multiple instances of the Address Autocomplete JavaScript Solution on the same page. This is useful for pages that contain multiple address forms, such as separate billing and shipping address sections.

Each instance must be initialized with selectors that point to the fields in the corresponding form. Here’s an example of how this can be done.

<script src="https://cdn.jsdelivr.net/npm/smarty-address/dist/smarty-address.iife.js"></script>

<script type="module">
const shippingAutocomplete = await SmartyAddress.create({
	embeddedKey: "your-smarty-embedded-key",
	streetSelector: "#shipping-street",
	citySelector: "#shipping-city",
	stateSelector: "#shipping-state",
	zipcodeSelector: "#shipping-zipcode",
});

const billingAutocomplete = await SmartyAddress.create({
	embeddedKey: "your-smarty-embedded-key",
	streetSelector: "#billing-street",
	citySelector: "#billing-city",
	stateSelector: "#billing-state",
	zipcodeSelector: "#billing-zipcode",
});
</script>

Each plugin instance operates independently and only fills the fields specified in its configuration.

API options

The plugin includes configuration options that control how autocomplete suggestions are requested and filtered.

These options are passed when the plugin is initialized.

For the full list of API options and advanced configuration details, see the npm README.

Themes

The Address Autocomplete JavaScript Solution can be styled to match your site’s design. Themes are configured during plugin initialization. Four built-in themes are available to choose from:

// Default theme (adapts to input colors)
const autocomplete = await SmartyAddress.create({
	theme: SmartyAddress.themes.default,
	// ...
});

// Light theme
const autocomplete = await SmartyAddress.create({
	theme: SmartyAddress.themes.light,
	// ...
});

// Dark theme
const autocomplete = await SmartyAddress.create({
	theme: SmartyAddress.themes.dark,
	// ...
});

// No styling (bring your own CSS)
const autocomplete = await SmartyAddress.create({
	theme: SmartyAddress.themes.none,
	// ...
});

Additional considerations for international autocomplete setup

By default, the Address Autocomplete JavaScript Solution is configured for US addresses. If you want to collect international addresses, here are the changes you'll need to make to your setup.

Set the country

The plugin defaults to "USA" until you specify otherwise, so the most important change is to specify the country you want to look up addresses for. You have two ways to do this:

• Set a static country using the country option with an ISO 3166-1 alpha-2 or alpha-3 code (e.g., "GB", "GBR", "DE", "FR").

const autocomplete = await SmartyAddress.create({
	embeddedKey: "your-smarty-embedded-key",
	country: "GBR",
	streetSelector: "#street",
	secondarySelector: "#secondary",
	localitySelector: "#city",
	administrativeAreaSelector: "#state",
	postalCodeSelector: "#zipcode",
});

• Let the user set the country through a form field using countrySelector, which points to a field (such as a text input where they enter a country code like "GBR") whose value is read at lookup time. If both are set, countrySelector takes precedence over country.

So in the form, add <input type="text" id="country" placeholder="Country code (e.g. GBR)" />, like this:

<form>
	<input type="text" id="country" placeholder="Country code (e.g. GBR)" />
	<input type="text" id="street" placeholder="Start typing an address..." />
	<input type="text" id="secondary" />
	<input type="text" id="city" />
	<input type="text" id="state" />
	<input type="text" id="zipcode" />
</form>

And the script should include countrySelector, like this:

const autocomplete = await SmartyAddress.create({
	embeddedKey: "your-smarty-embedded-key",
	countrySelector: "#country",
	streetSelector: "#street",
	secondarySelector: "#secondary",
	localitySelector: "#city",
	administrativeAreaSelector: "#state",
	postalCodeSelector: "#zipcode",
});

Whatever the user types into the country field is what the plugin sends as the country on each lookup, so once they enter "GBR", the autocomplete solution only pulls UK addresses. If they change it to "CAN" and keep typing an address, the very next lookup (keystroke) brings up Canadian addresses.