@addresso/react

React hooks and components for Addresso UK address lookups.

Installation

npm install @addresso/react

Quick start

Using the component

import { AddressoProvider, AddressoLookup } from "@addresso/react";
import "@addresso/react/styles.css";

function App() {
  return (
    <AddressoProvider apiKey="ak_...">
      <AddressoLookup onSelect={(address) => console.log(address)} />
    </AddressoProvider>
  );
}

Using the hook

import { AddressoProvider, useAddresso } from "@addresso/react";

function AddressForm() {
  const { lookupPostcode, addresses, isLoading, error } = useAddresso();

  return (
    <div>
      <button onClick={() => lookupPostcode("SW1A 1AA")}>
        {isLoading ? "Loading..." : "Look up"}
      </button>
      {error && <p>{error.message}</p>}
      <ul>
        {addresses.map((a) => (
          <li key={a.udprn}>
            {a.building_number} {a.street}, {a.town} {a.postcode}
          </li>
        ))}
      </ul>
    </div>
  );
}

function App() {
  return (
    <AddressoProvider apiKey="ak_...">
      <AddressForm />
    </AddressoProvider>
  );
}

Using the client directly (no React)

import { AddressoClient } from "@addresso/react";

const client = new AddressoClient({ apiKey: "ak_..." });

const result = await client.lookupPostcode("SW1A 1AA");
console.log(result.addresses);

const search = await client.searchAddresses({ q: "10 Downing Street" });
console.log(search.addresses);

API

<AddressoProvider>

Wraps your app and provides the API client to all hooks and components.

| Prop | Type | Required | Description | | --------- | -------- | -------- | -------------------------------------------- | | apiKey | string | Yes | Your Addresso API key (ak_...) | | baseUrl | string | No | Override API base URL (default: https://addresso.co.uk) |

useAddresso()

Headless hook for address lookups. Must be used within <AddressoProvider>.

Returns:

| Property | Type | Description | | ----------------- | ----------------------------------------------- | ---------------------------------- | | lookupPostcode | (postcode: string) => Promise<PostcodeLookupResponse> | Look up addresses by postcode | | searchAddresses | (params: AddressSearchParams) => Promise<AddressSearchResponse> | Search addresses by various fields | | addresses | AddressoAddress[] | Addresses from the last lookup | | isLoading | boolean | Whether a request is in progress | | error | Error \| null | Error from the last request | | reset | () => void | Clear addresses, error, and loading state |

<AddressoLookup>

Ready-made postcode lookup component with input, button, and dropdown. Must be used within <AddressoProvider>.

| Prop | Type | Default | Description | | ---------------- | ----------------------------------------- | ----------------- | ----------------------------------- | | onSelect | (address: AddressoAddress) => void | Required | Called when user selects an address | | placeholder | string | "Enter postcode" | Input placeholder text | | buttonText | string | "Find address" | Search button text | | className | string | — | Additional CSS class | | style | CSSProperties | — | Inline styles | | renderAddress | (address: AddressoAddress) => ReactNode | — | Custom address rendering | | disabled | boolean | false | Disable the input and button | | inputLabel | string | "Postcode" | Label for the input field |

AddressoClient

Standalone client class with no React dependency.

const client = new AddressoClient({ apiKey: "ak_...", baseUrl: "..." });
await client.lookupPostcode("SW1A 1AA");
await client.searchAddresses({ q: "Buckingham Palace", limit: 10 });

Types

AddressoAddress

interface AddressoAddress {
  postcode: string;
  town: string;
  locality: string;
  sub_locality: string;
  street: string;
  secondary_street: string;
  building_number: string;
  building_name: string;
  sub_building: string;
  po_box: string;
  department: string;
  organisation: string;
  udprn: number;
  postcode_type: string;
  delivery_point_suffix: string;
  latitude: number | null;
  longitude: number | null;
}

AddressSearchParams

interface AddressSearchParams {
  q?: string;
  postcode?: string;
  town?: string;
  street?: string;
  building_name?: string;
  building_number?: string;
  organisation?: string;
  limit?: number;
}

Styling

Import the default styles for <AddressoLookup>:

import "@addresso/react/styles.css";

All classes use BEM naming (addresso-lookup__*) so you can easily override them.

License

MIT