smarty-address

A lightweight TypeScript library for adding Smarty address autocomplete and validation to any web form.

Installation

npm install smarty-address

Quick Start

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

<script type="module">
  import SmartyAddress from "smarty-address";

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

Via CDN

Use the library directly in the browser without a build step:

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

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

The CDN script adds a global SmartyAddress object with the same API as the module import. You can also use unpkg as an alternative CDN.

Get your embedded key from the Smarty dashboard.

Configuration

Required Options

| 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 gets populated:

| 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 city field | | stateSelector | string | CSS selector for state field | | zipcodeSelector | string | CSS selector for ZIP code field |

International Naming

For international address forms, you can use alternative names that align with Smarty's international API conventions:

| US Name | International Alternative | |---------|--------------------------| | citySelector | localitySelector | | stateSelector | administrativeAreaSelector, regionSelector, provinceSelector | | zipcodeSelector | postalCodeSelector, postcodeSelector, zipSelector |

API Options

These options control the suggestions returned by the Smarty API:

| Option | Type | Description | |--------|------|-------------| | maxResults | number | Maximum number of suggestions to return | | includeOnlyCities | string[] | Only return addresses in these cities | | includeOnlyStates | string[] | Only return addresses in these states | | includeOnlyZipCodes | string[] | Only return addresses in these ZIP codes | | excludeStates | string[] | Exclude addresses in these states | | preferCities | string[] | Prefer addresses in these cities | | preferStates | string[] | Prefer addresses in these states | | preferZipCodes | string[] | Prefer addresses in these ZIP codes | | preferRatio | number | Ratio of preferred results (0-100) | | preferGeolocation | string | Prefer results near a geolocation | | source | "postal" \| "all" | Address data source |

International Naming

API filter options also accept international alternatives:

| US Name | International Alternative | |---------|--------------------------| | includeOnlyCities | includeOnlyLocalities | | includeOnlyStates | includeOnlyAdministrativeAreas | | includeOnlyZipCodes | includeOnlyPostalCodes | | excludeStates | excludeAdministrativeAreas | | preferCities | preferLocalities | | preferStates | preferAdministrativeAreas | | preferZipCodes | preferPostalCodes |

Lifecycle Hooks

Hooks let you respond to events and customize behavior:

const autocomplete = await SmartyAddress.create({
  embeddedKey: "your-key",
  streetSelector: "#street",

  onAddressSelected: (address) => {
    console.log("User selected:", address);
    // address contains: street_line, secondary, city, state, zipcode, country
  },

  onAutocompleteSuggestionsReceived: (suggestions) => {
    // Filter or modify suggestions before display
    return suggestions.filter((s) => s.state !== "CA");
  },

  onDropdownOpen: () => {
    console.log("Dropdown opened");
  },

  onDropdownClose: () => {
    console.log("Dropdown closed");
  },
});

| Hook | Signature | Description | |------|-----------|-------------| | onAddressSelected | (address: AutocompleteSuggestion) => void | Called when user selects an address | | onAutocompleteSuggestionsReceived | (suggestions: AutocompleteSuggestion[]) => AutocompleteSuggestion[] | Called when suggestions arrive; return modified array | | onDropdownOpen | () => void | Called when dropdown opens | | onDropdownClose | () => void | Called when dropdown closes |

Themes

Four built-in themes are available:

import SmartyAddress from "smarty-address";

// 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,
  // ...
});

Custom Themes

Themes are arrays of CSS class names applied to the plugin components. Each class defines CSS variables that control the plugin's appearance (see assets/styles/ for examples). Create a custom theme by providing your own array:

const autocomplete = await SmartyAddress.create({
  theme: ["my-dropdown-theme", "my-color-scheme"],
  // ...
});

You can also extend a built-in theme:

const autocomplete = await SmartyAddress.create({
  theme: [...SmartyAddress.themes.dark, "my-custom-overrides"],
  // ...
});

Multiple Instances

Create multiple autocomplete inputs on the same page by creating multiple SmartyAddress instances:

const shippingAutocomplete = await SmartyAddress.create({
  embeddedKey: "your-key",
  searchInputSelector: "#shipping-address",
  streetSelector: "#shipping-street",
  citySelector: "#shipping-city",
  stateSelector: "#shipping-state",
  zipcodeSelector: "#shipping-zip",
});

const billingAutocomplete = await SmartyAddress.create({
  embeddedKey: "your-key",
  searchInputSelector: "#billing-address",
  streetSelector: "#billing-street",
  citySelector: "#billing-city",
  stateSelector: "#billing-state",
  zipcodeSelector: "#billing-zip",
});

Each instance operates independently with isolated state.

Cleanup

When you no longer need an autocomplete instance (e.g., when navigating away in a single-page application), call destroy() to clean up event listeners and DOM elements:

const autocomplete = await SmartyAddress.create({
  embeddedKey: "your-key",
  streetSelector: "#street",
});

// Later, when done with the autocomplete:
autocomplete.destroy();

This removes all event listeners, disconnects observers, and removes injected DOM elements to prevent memory leaks.

Service Overrides

For advanced customization, you can extend and replace any internal service:

import SmartyAddress from "smarty-address";

class CustomApiService extends SmartyAddress.services.ApiService {
  // Override methods to customize API behavior
}

class CustomFormService extends SmartyAddress.services.FormService {
  // Override methods to customize form population
}

const autocomplete = await SmartyAddress.create({
  embeddedKey: "your-key",
  streetSelector: "#street",
  services: {
    ApiService: CustomApiService,
    FormService: CustomFormService,
  },
});

Available Services

| Service | Purpose | |---------|---------| | ApiService | Handles Smarty API calls and response processing | | DropdownService | Manages dropdown UI orchestration, DOM creation, and event handling | | DropdownStateService | Manages dropdown state (open/close, selected items, suggestion tracking) | | KeyboardNavigationService | Handles keyboard navigation within the dropdown (arrow keys, enter, escape) | | FormService | Populates form fields when an address is selected | | DomService | Generic DOM utilities for element creation, manipulation, and form value handling | | StyleService | CSS generation, dynamic style calculation, and style block formatting | | FormatService | Address formatting for display and text highlighting for search matches | | ColorService | Color conversion utilities (RGB/HSL), CSS color parsing, and percentage conversions |

All services extend BaseService which provides:

• setServices(services) - Receives references to all other services
• init(config) - Called with configuration (override as needed)
• Typed protected getters (e.g., this.apiService, this.formService) to access other services

API Reference

Static Methods

| Method | Signature | Description | |--------|-----------|-------------| | SmartyAddress.create | (config: SmartyAddressConfig) => Promise<SmartyAddress> | Creates and initializes a new autocomplete instance |

Instance Methods

| Method | Signature | Description | |--------|-----------|-------------| | destroy | () => void | Removes all event listeners, observers, and DOM elements |

Static Properties

| Property | Type | Description | |----------|------|-------------| | SmartyAddress.themes | object | Built-in theme presets (default, light, dark, none) | | SmartyAddress.services | object | Service classes for extension | | SmartyAddress.defaultConfig | object | Default configuration values |

AutocompleteSuggestion Object

The address object passed to hooks contains:

interface AutocompleteSuggestion {
  street_line: string;
  secondary?: string;
  city: string;
  state: string;
  zipcode: string;
  country: string;
  entries?: number;
  metadata?: Record<string, unknown>;
}