@mountainpass/addressr-vue

@mountainpass/addressr-vue

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

Part of the addressr-ui monorepo.

Install

npm install @mountainpass/addressr-vue

Peer dependencies: vue >= 3.3.

Drop-in component

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

function handleSelect(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, ... }
}
</script>

<template>
  <AddressAutocomplete
    api-url="https://api.addressr.io/"
    @select="handleSelect"
  />
</template>

Props

Prop	Type	Default	Description
apiKey	string	--	RapidAPI key. Omit for direct API access.
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

Events

Event	Payload	Description
select	AddressDetail	Emitted when an address is selected

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

<template>
  <AddressAutocomplete api-url="https://api.addressr.io/" @select="handleSelect">
    <template #loading><li>Loading addresses...</li></template>
    <template #no-results><li>No matches found</li></template>
  </AddressAutocomplete>
</template>

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

Headless composable

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

<script setup>
import { useAddressSearch } from '@mountainpass/addressr-vue';

const {
  query, setQuery,
  results, isLoading,
  hasMore, loadMore, isLoadingMore,
  selectedAddress, selectAddress,
  error, clear,
} = useAddressSearch({ apiUrl: 'https://api.addressr.io/' });
</script>

<template>
  <input :value="query" @input="setQuery($event.target.value)" />
  <ul>
    <li v-for="r in results" :key="r.pid" @click="selectAddress(r.pid)">
      {{ r.sla }}
    </li>
    <li v-if="hasMore" @click="loadMore()">Load more...</li>
  </ul>
</template>

Return values

All return values are Vue Refs (use .value in script, auto-unwrapped in templates):

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

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

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 composables. Each mirrors AddressAutocomplete's a11y, keyboard, and slot contract; the only difference is the select event payload is the SearchResult itself (no follow-up detail fetch — see ADR 006).

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

<template>
  <PostcodeAutocomplete api-key="..." @select="(r) => console.log(r.postcode, r.localities)" />
  <LocalityAutocomplete api-key="..." @select="(r) => console.log(r.name, r.state.abbreviation, r.postcode)" />
  <StateAutocomplete    api-key="..." @select="(r) => console.log(r.name, r.abbreviation)" />
</template>

Headless equivalents usePostcodeSearch, useLocalitySearch, useStateSearch are also exported and follow the same shape as useAddressSearch.

Re-exports

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

License

Apache-2.0