All tutorials
Address Autocomplete Component: Integrate Swiftcomplete into Web Forms
The Swiftcomplete API provides real-time address suggestions as you type, eliminating typos and mistakes and reducing the time it takes to find accurate postal addresses.
If you need help integrating our Swiftcomplete API into your website or application, contact us, and one of our product experts will help you get started.
If you’re looking for the guide for previous version of the Swiftcomplete JavaScript component, you can find it here.
Each request must be authenticated with a Swiftcomplete API key, which you can create in your Swiftcomplete account.
Pick your framework. Each tab below is a working snippet. Copy it, drop in your API key, and you have address search.
No build step, no npm. Add one script tag and one element.
<swiftcomplete-search api-key="YOUR_API_KEY" country="gb" placeholder="Search address or postcode" name="address"></swiftcomplete-search> <script type="module" src="https://assets.swiftcomplete.com/javascript-components@1.0.0/dist/swiftcomplete.es.js"></script>
That is a working address search. To do something with the result, listen for the select event:
<script type="module"> const el = document.querySelector('swiftcomplete-search'); el.addEventListener('swiftcomplete:swiftcomplete:select', (e) => { const address = e.detail.selected; console.log(address.addressLine1, address.city, address.postalCode); }); </script>
Most integrations want the selected address split across the fields of an existing checkout form. Give the component a map of your field IDs and it fills them in on selection.
<swiftcomplete-search api-key="YOUR_API_KEY" country="gb"></swiftcomplete-search> <input id="address-line-1" name="line1"> <input id="address-line-2" name="line2"> <input id="address-city" name="city"> <input id="address-postcode" name="postcode"> <input id="address-w3w" name="what3words">
const el = document.querySelector('swiftcomplete-search'); el.populateFields({ addressLine1: { fieldId: 'address-line-1', format: 'AddressLine1' }, addressLine2: { fieldId: 'address-line-2', format: 'AddressLine2' }, city: { fieldId: 'address-city', format: 'TertiaryLocality, SecondaryLocality, PrimaryLocality' }, postalCode: { fieldId: 'address-postcode', format: 'POSTCODE' }, what3words: { fieldId: 'address-w3w', format: 'what3words' }, });
When the user picks a result, each fieldId is looked up with document.getElementById() and its value is set. Only <input> elements are filled; anything else logs a warning naming the key.
e.detail.selected. They’re your own labels, not fixed names, so if you map postalcode, you read back selected.postalcode, not selected.postalCode. Match the default key names below unless you have a reason not to. The one key that is special is what3words, which the component recognises and fills with the three word address.Call populateFields() once the component is in the DOM, and make sure each fieldId matches exactly one element.
Default address keys
If you never call populateFields, e.detail.selected still arrives with these keys:
| KEY | FORMAT STRING | EXAMPLE |
|---|---|---|
| company | Company | what3words Ltd |
| addressLine1 | AddressLine1 | 65 Alfred Road |
| addressLine2 | AddressLine2 | |
| city | TertiaryLocality, SecondaryLocality, PrimaryLocality | London |
| postalCode | POSTCODE | W2 5EU |
| country | PrimaryCountry | United Kingdom |
| what3words | what3words | filled.count.soap |
There are two ways to configure the component, and you can mix them freely. Attributes are simplest for a static page; the JavaScript API is better when settings come from config, or when you need to change them at runtime.
Set everything on the tag. Attributes are live: change one at runtime and the component updates.
<swiftcomplete-search api-key="YOUR_API_KEY" country="gb" placeholder="Type your address or postcode" name="address-search" variant="outlined" size="large" theme="light"></swiftcomplete-search>
Good for static pages, server-rendered templates and CMS blocks where the key is safe to put in markup.
Three things most integrations reach for eventually. None are required to get started.
The component can search addresses (the default), three word addresses, or both in the same input. This is controlled on the service, not per element, so every search field on the page follows it.
window.swiftcomplete.runWhenReady((api) => { api.setApiKey('YOUR_API_KEY'); api.setSearchFor('address'); // default api.setSearchFor('what3words'); // three word addresses only api.setSearchFor('address', 'what3words'); // both in one box });
Any field without an explicit placeholder updates its own wording to match. To capture the three word address, add a what3words entry to your field map.
https://what3words.com/filled.count.soap, the component strips the URL and searches the three words, including locale subdomains.Attributes
| ATTRIBUTE | VALUES | DESCRIPTION |
|---|---|---|
| api-key | string | Your Swiftcomplete API key. |
| country | ISO 3166-1 alpha-2 | Restrict suggestions to one country. Omit to search all available countries. |
| placeholder | string | Placeholder text. If omitted it follows what you're searching for: "Type your address or postcode", or "Type your address, what3words, or postcode" when both are enabled. |
| name | string | Form field name, so the value submits with your form. |
| value | string | Initial value of the input. |
| variant | outlined · filled · minimal · modern | Preset visual style. |
| size | default · small · large | Scales font and icon size. |
| theme | auto · light · dark | auto is the default and follows the page's prefers-color-scheme. |
| class / style | string | Copied onto the inner input. Layout properties are ignored; style the host element for those. |
Events
All events fire on the <swiftcomplete-search> element. They bubble and are composed, so they cross the shadow boundary and you can listen on a parent element or on document instead. The constants in SearchEvents and FieldEvents are the same strings, so you can use either.
| EVENT | CONSTANT | EVENT.DETAIL |
|---|---|---|
| swiftcomplete:swiftcomplete:start | SearchEvents.Start | { query } |
| swiftcomplete:swiftcomplete:end | SearchEvents.End | { query, success, results?, reason?, canceled? } |
| swiftcomplete:swiftcomplete:select | SearchEvents.Select | { index, selected } |
| swiftcomplete:swiftcomplete:manualentry | SearchEvents.ManualEntry | None |
| swiftcomplete:field:clear | FieldEvents.Clear | None |
| swiftcomplete:field:focus | FieldEvents.Focus | None |
| swiftcomplete:field:blur | FieldEvents.Blur | None |
Service methods
Available on the api object passed to runWhenReady.
| METHOD | DEFAULT | DESCRIPTION |
|---|---|---|
| setApiKey(key) | None | Sets the API key for every component on the page. |
| setCountry(code) | all countries | Restricts suggestions to one country. |
| setSearchFor(...types) | 'address' | Pass 'address', 'what3words' or both. |
| setResultOrdering(order) | None | location_biasing |
| setHideOnEmptyResults(bool) | false | Hide the dropdown instead of showing "no results". |
| setEnableSearchOnEmptySearch(bool) | false | Show nearby roads on focus, before the user types. |
| enableDeviceLocation() | off | Asks for browser geolocation and biases results towards the user. |
setSearchFor('address', 'what3words'). The v1 component’s snippet enabled both, so this is a deliberate step when migrating.Supported countries
Austria at · Canada ca · Denmark dk · France fr · Germany de · Guernsey gg · Isle of Man im · Italy it · Jersey je · Liechtenstein li · Luxembourg lu · Netherlands nl · Norway no · Switzerland ch · United Kingdom gb
Styling
The component renders inside a shadow root, so your page’s CSS won’t reach into it. Style it by setting custom properties on the element.
swiftcomplete-search { --swiftcomplete-input-border-radius: 4px; --swiftcomplete-focus-border-color: #e11f26; --swiftcomplete-font-family: inherit; --swiftcomplete-padding: 0.75em; --swiftcomplete-result-max-items: 6; }
| CUSTOM PROPERTY | DEFAULT |
|---|---|
| --swiftcomplete-background | #fff |
| --swiftcomplete-primary-text-color | #474747 |
| --swiftcomplete-secondary-text-color | #707070 |
| --swiftcomplete-focus-border-color | #007bff |
| --swiftcomplete-error-color | #dc3545 |
| --swiftcomplete-input-border | 1px solid #dedede |
| --swiftcomplete-input-border-radius | 8px |
| --swiftcomplete-padding | 1em |
| --swiftcomplete-icon-size | 16px |
| --swiftcomplete-result-max-items | 5 (4 on tablet, 3 on mobile) |
| --swiftcomplete-min-width | 250px |