New 42-day free trial Get it now
Smarty

Smarty Address Plugin v1.0

The Smarty Address Plugin is a lightweight JavaScript tool that makes it easy to add Smarty’s US 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
  2. Field definitions
  3. Advanced options

Quick start

The Smarty Address Plugin 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 Smarty Address Plugin 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 Smarty Address Plugin to work.

Option Type Description
embeddedKey string Your Smarty embedded key
streetSelector string CSS selector for street address field (also used as the autocomplete input unless searchInputSelector is provided)

Form field selectors

These selectors define where the selected address data will populate.

Option Type Description
searchInputSelector string CSS selector for the autocomplete input. Only needed when the autocomplete input is a different element from where the street address will be populated (e.g., a unified search field that populates separate street/city/state fields)
secondarySelector string CSS selector for secondary address (apt, suite, etc.)
citySelector string CSS selector for the “city” field
stateSelector string CSS selector for the “state” field
zipcodeSelector string CSS selector for the “ZIP Code” field

Advanced options

The Smarty Address Plugin 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 Smarty Address Plugin 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.

Name Type Default value Description
source string postal Include results from alternate data sources. Allowed values are:
all - will include non-postal addresses in the results
postal - will limit the results to postal addresses only

If this parameter is used, an additional field named source will be returned for each result, which is either postal for postal addresses, or other if the address is from an alternate data source.
maxResults integer 10 Maximum number of address suggestions to return; range [1, 10].
includeOnlyCities string (empty) Limit the results to only those cities and states listed, as well as those in includeOnlyStates.
IMPORTANT: This field must contain a state after the list of cities as shown in the example.
Another important note is that you should NOT list a state mentioned within this field in the includeOnlyStates field as it takes precedence over this field.
Example: DENVER,AURORA,CO;OMAHA,NE See filtering for more information.
includeOnlyStates string (empty) Limit the results to only those states listed, as well as those listed in includeOnlyCities.
IMPORTANT: If a state is mentioned in the includeOnlyCities field, you should NOT include that same state in this field as it will take precedence. Examples: UT;ID;MT or CONTIGUOUS or ALLSTATES See filtering for more information.
includeOnlyZipCodes string (empty) Limit the results to only those ZIP Codes listed. When this parameter is used, no other cities, states parameters can be used.
Note: When using this parameter, the preferGeolocation parameter must NOT be set to city.
Example: 90210;06504 See filtering for more information.
excludeStates string (empty) Exclude the following states from the results. When this parameter is used, no other include parameters may be used.
Note: The preferGeolocation parameter MUST be set to none if the customer's current location is in a state specified in this parameter; otherwise the customer will see addresses from their current location.
Example: SD;ND;MT See filtering for more information.
preferCities string (empty) Display suggestions with the listed cities and states at the top of the suggestion list, as well as those listed in preferStates. Example: DENVER,AURORA,CO;OMAHA,NE See preferencing for more information.
preferStates string (empty) Display suggestions with the listed states at the top of the suggestion list, as well as those listed in preferCities.
Examples: UT;ID;MT See preferencing for more information.
preferZipCodes string (empty) Display suggestions with the listed ZIP Codes at the top of the suggestion list. When this parameter is used, no other cities or states parameters can be used.
Note: When using this parameter, the preferGeolocation parameter must NOT be set to city.
See preferencing for more information.
preferRatio integer 100 Specifies the percentage of address suggestions that should be preferred and will appear at the top of the suggestion list. Expressed as an integer value, range [0, 100]. See preferencing for more information.
preferGeolocation string city If omitted or set to city, it uses the sender's IP address (IPv4 only) to determine location, then automatically adds the city and state to the preferCities value. This parameter takes precedence over other include or exclude parameters meaning that if it is not set to none, you may see addresses from the customer's area when you may not desire it.
Acceptable values are: empty string (which defaults to city), none, or city.
Notes:
1. If any zipCodes parameters are used, this parameter must NOT be set to city)
2. If the request to the Autocomplete Pro API goes through a proxy, you will need to set an X-Forwarded-For header specifying the user's IP address.

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

Themes

The Smarty Address Plugin 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,
	// ...
});

Ready to get started?

Schedule Demo
42-day Free Trial