@mountainpass/addressr-svelte

@mountainpass/addressr-svelte

Svelte address autocomplete component for Australian address search, powered by Addressr.

Part of the addressr-ui monorepo.

Install

npm install @mountainpass/addressr-svelte

Peer dependencies: svelte >= 4.

Drop-in component

<script>
  import { AddressAutocomplete } from '@mountainpass/addressr-svelte';
  import '@mountainpass/addressr-svelte/style.css';
</script>

<AddressAutocomplete
  apiUrl="https://api.addressr.io/"
  onSelect={(address) => {
    console.log(address.sla);          // "1 GEORGE ST, SYDNEY NSW 2000"
    console.log(address.structured);   // { street, locality, state, postcode, ... }
    console.log(address.geocoding);    // { latitude, longitude, ... }
  }}
/>

Props

Prop	Type	Default	Description
apiKey	string	--	RapidAPI key. Omit for direct API access.
onSelect	(address: AddressDetail) => void	--	Called when an address is selected
label	string	"Search Australian addresses"	Accessible label text
placeholder	string	"Start typing an address..."	Input placeholder
debounceMs	number	300	Debounce delay in milliseconds
name	string	"address"	Input name attribute for form submission
required	boolean	false	Sets aria-required on the input
apiUrl	string	"https://addressr.p.rapidapi.com/"	API root URL
apiHost	string	"addressr.p.rapidapi.com"	RapidAPI host header

Slots

Override rendering zones while keeping built-in search logic and keyboard navigation:

Slot	Default	Description
loading	Animated skeleton lines	Custom loading state
no-results	"No addresses found" message	Custom empty state

<AddressAutocomplete apiUrl="https://api.addressr.io/" onSelect={handleSelect}>
  <li slot="loading">Loading addresses...</li>
  <li slot="no-results">No matches found</li>
</AddressAutocomplete>

When you provide a custom slot, you are responsible for accessibility in that zone.

Headless store

Build your own UI while keeping the search logic, debounce, pagination, and abort handling:

<script>
  import { createAddressSearch } from '@mountainpass/addressr-svelte';

  const search = createAddressSearch({ apiUrl: 'https://api.addressr.io/' });

  function handleInput(e) {
    search.setQuery(e.target.value);
  }
</script>

<input value={$search.query} on:input={handleInput} />

{#if $search.isLoading}
  <p>Searching...</p>
{/if}

<ul>
  {#each $search.results as result}
    <li on:click={() => search.selectAddress(result.pid)}>{result.sla}</li>
  {/each}
  {#if $search.hasMore}
    <li on:click={() => search.loadMore()}>Load more...</li>
  {/if}
</ul>

Store state ($search)

Property	Type	Description
query	string	Current input value
results	AddressSearchResult[]	Search results (accumulated across pages)
isLoading	boolean	Initial search in progress
isLoadingMore	boolean	Pagination fetch in progress
hasMore	boolean	More pages available
error	Error | null	Latest error
selectedAddress	AddressDetail | null	Selected address detail

Store methods

Method	Description
setQuery(q)	Update query (triggers debounced search)
loadMore()	Load next page of results
selectAddress(pid)	Fetch full address detail
clear()	Reset all state
destroy()	Clean up timers and abort controllers

Theming

All visual styles use CSS custom properties. Override on any ancestor element:

.my-form {
  --addressr-font-family: 'Inter', sans-serif;
  --addressr-border-color: #ccc;
  --addressr-focus-color: #0066cc;
  --addressr-highlight-bg: #e0f0ff;
  --addressr-error-color: #c62828;
}

Token	Default	Description
--addressr-font-family	system-ui, -apple-system, sans-serif	Font stack
--addressr-padding-x	0.75rem	Horizontal padding
--addressr-padding-y	0.625rem	Vertical padding
--addressr-text-color	inherit	Text color
--addressr-border-color	#767676	Input and dropdown border
--addressr-border-radius	0.25rem	Corner radius
--addressr-focus-color	#005fcc	Focus ring and border
--addressr-z-index	1000	Dropdown stacking order
--addressr-bg	#fff	Dropdown background
--addressr-shadow	0 4px 6px rgba(0,0,0,0.1)	Dropdown shadow
--addressr-highlight-bg	#e8f0fe	Active item background
--addressr-mark-weight	700	Search match font weight
--addressr-mark-color	inherit	Search match text color
--addressr-muted-color	#555	Status and empty text
--addressr-error-color	#d32f2f	Error message text
--addressr-skeleton-from	#e0e0e0	Loading skeleton base
--addressr-skeleton-to	#f0f0f0	Loading skeleton shimmer

The loading state shows animated skeleton lines instead of text. The animation respects prefers-reduced-motion: reduce.

Accessibility

Implements the WAI-ARIA combobox pattern:

• Full keyboard navigation (Arrow keys, Enter, Escape)
• Screen reader announcements for results count and loading state
• Visible focus indicators (3:1 contrast)
• Touch targets >= 44px
• Accessible label always present
• Infinite scroll with loading indicator

Postcode, Locality, and State search

For narrower lookups (postcode-only picker on a shipping form, suburb autocomplete, state dropdown) the package also exports three drop-in components and matching headless stores. Each mirrors AddressAutocomplete's a11y, keyboard, and slot contract; the only difference is onSelect receives the SearchResult directly (no follow-up detail fetch — see ADR 006).

<script>
  import {
    PostcodeAutocomplete,
    LocalityAutocomplete,
    StateAutocomplete,
  } from '@mountainpass/addressr-svelte';
</script>

<PostcodeAutocomplete apiKey="..." onSelect={(r) => console.log(r.postcode, r.localities)} />
<LocalityAutocomplete apiKey="..." onSelect={(r) => console.log(r.name, r.state.abbreviation, r.postcode)} />
<StateAutocomplete    apiKey="..." onSelect={(r) => console.log(r.name, r.abbreviation)} />

Headless equivalents createPostcodeSearch, createLocalitySearch, createStateSearch are also exported and follow the same shape as createAddressSearch.

Re-exports

This package re-exports everything from @mountainpass/addressr-core for convenience -- createAddressrClient, parseHighlight, and all types.

License

Apache-2.0