React

A headless hook, ready-made component, and standalone client for integrating Addresso address lookups into React apps. Full TypeScript support included.

npm — @addresso/react

Installation

Requires React 18 or later.

bash

npm install @addresso/react

Provider

Wrap your app (or the part that needs address lookups) with <AddressoProvider>. This makes your API key available to all hooks and components below it.

tsx

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

function App() {
  return (
    <AddressoProvider apiKey="ak_your_api_key">
      <YourApp />
    </AddressoProvider>
  );
}

Props

apiKeystringrequired

Your Addresso API key (begins with ak_).

baseUrlstring

Override the API base URL. Defaults to https://addresso.co.uk.

Component

<AddressoLookup> renders a postcode input, search button, and address dropdown. Import the optional CSS for default styling. Must be inside an <AddressoProvider>.

tsx

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

function CheckoutForm() {
  return (
    <AddressoLookup
      onSelect={(address) => {
        console.log(address.building_number, address.street);
        console.log(address.town, address.postcode);
      }}
      placeholder="Enter postcode"
      buttonText="Find address"
    />
  );
}

Props

onSelectfunctionrequired

Called with the full AddressoAddress object when a user picks an address from the dropdown.

placeholderstring

Input placeholder text. Defaults to "Enter postcode".

buttonTextstring

Search button label. Defaults to "Find address".

classNamestring

Additional CSS class on the wrapper element.

styleCSSProperties

Inline styles on the wrapper element.

renderAddressfunction

Custom render function for each dropdown item. Receives an AddressoAddress.

disabledboolean

Disables the input and button. Defaults to false.

inputLabelstring

Accessible label for the input. Defaults to "Postcode".

Styling

Import @addresso/react/styles.css for minimal default styling. All classes use BEM naming (addresso-lookup__*) so you can easily override them or write your own from scratch.

Hook

useAddresso() gives you full control over the UI. It returns lookup functions that update shared state and return promises. Must be inside an <AddressoProvider>.

tsx

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

function AddressForm() {
  const {
    lookupPostcode,
    searchAddresses,
    addresses,
    isLoading,
    error,
    reset,
  } = 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}
          </li>
        ))}
      </ul>
    </div>
  );
}

Return values

lookupPostcodefunction

(postcode: string) => Promise — look up all addresses at a postcode. Updates addresses.

searchAddressesfunction

(params) => Promise — search by free text, street, town, etc. Updates addresses.

addressesAddressoAddress[]

Array of addresses from the most recent lookup.

isLoadingboolean

true while a request is in flight.

errorError | null

Error from the most recent request, or null.

resetfunction

Clears addresses, error, and loading state.

Standalone client

The AddressoClient class works without React — use it in Node scripts, server components, or any TypeScript/JavaScript project. No provider needed.

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

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

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

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