What is the @ahm-labs/fast-address-uk package?

It is the official zero-dependency TypeScript SDK for FastAddress UK, providing sub-15ms address autocompletion, UPRN geocoding, and React hooks.

Does the React hook handle debouncing automatically?

Yes, useFastAddress from @ahm-labs/fast-address-uk/react includes configurable built-in debouncing (default 200ms) and automatic cancellation of in-flight requests.

Home / Docs / NPM Package Reference

📦 NPM REGISTRY PACKAGE

@ahm-labs/fast-address-uk

The official zero-dependency TypeScript/JavaScript client and React hook library for FastAddress UK. Published to the public npm registry under the MIT license.

View on npmjs.com ↗v1.1.0< 2.5 KB gzippedMIT License

1. Installation

Terminal

npm install @ahm-labs/fast-address-uk
# or
pnpm add @ahm-labs/fast-address-uk
# or
yarn add @ahm-labs/fast-address-uk

2. Accessible React Component (`AddressAutocomplete`)

Drop-in WAI-ARIA 1.2 accessible combobox with keyboard navigation (Arrow keys, Enter, Escape) and zero configuration:

CheckoutForm.tsx

import { AddressAutocomplete } from '@ahm-labs/fast-address-uk/react';

export function CheckoutForm() {
  return (
    <AddressAutocomplete
      apiKey="demo"
      onSelect={(addr) => console.log('Selected:', addr)}
      placeholder="Start typing postcode or street name..."
    />
  );
}

3. Headless React Hook (`useFastAddress`)

Import the headless useFastAddress hook from @ahm-labs/fast-address-uk/react for custom UI:

AddressSearch.tsx

import { useFastAddress } from '@ahm-labs/fast-address-uk/react';

export function SearchComponent() {
  const { query, results, isLoading, search, clear } = useFastAddress({
    debounceMs: 200,
    minQueryLength: 2
  });

  return (
    <div>
      <input value={query} onChange={(e) => search(e.target.value)} placeholder="Type address..." />
      {isLoading && <span>Searching...</span>}
      <ul>
        {results.map((r) => (
          <li key={r.id || r.uprn}>{r.address_string} ({r.postcode})</li>
        ))}
      </ul>
    </div>
  );
}

4. Vanilla TypeScript & Node.js

Import the core fetcher from the root package. Works in Node 18+, Bun, Deno, and Edge Workers with built-in client LRU caching:

index.ts

import { lookupAddress, createFastAddressClient } from '@ahm-labs/fast-address-uk';

// 1. One-off autocomplete lookup
const results = await lookupAddress('10 Downing Street', { limit: 5 });
console.log(results[0].address_string, results[0].uprn, results[0].postcode);

// 2. Reusable client instance with LRU caching
const client = createFastAddressClient({
  apiKey: process.env.FAST_ADDRESS_KEY,
  defaultLimit: 10
});

const addresses = await client.lookup('SW1A 1AA');

5. Standalone Browser CDN

Zero-build script tag for WordPress, Shopify, Webflow, or legacy web applications:

index.html

<!-- Load Standalone Bundle (< 4.5 KB) -->
<script src="https://fastaddress.ahm-labs.com/sdk/fast-address.min.js"></script>

<input id="address-input" type="text" placeholder="Type UK address..." />

<script>
  FastAddress.attachToInput('#address-input', {
    onSelect: function(address) {
      console.log('Selected UPRN:', address.uprn);
      console.log('Coordinates:', address.latitude, address.longitude);
    }
  });
</script>

6. TypeScript Interfaces

types.d.ts

export interface AddressResult {
  id: number;              // Unique database identifier
  address_string: string;  // Formatted address line
  postcode: string;        // Official Royal Mail UK postcode
  latitude: number;        // WGS84 GPS Latitude
  longitude: number;       // WGS84 GPS Longitude
  uprn: number | null;     // Ordnance Survey 12-digit UPRN
}

export interface LookupOptions {
  apiKey?: string;
  baseUrl?: string;
  limit?: number;
  signal?: AbortSignal;
  timeoutMs?: number;
  cache?: boolean;
  headers?: Record<string, string>;
}