Skip to main content

Anything integration rules

This page is the detailed rule set referenced by the Anything starter prompt. It exists so the prompt you paste into the builder can stay short. The agent fetches this page and follows the rules below. It is intentionally kept out of the sidebar.

Anything builds React apps, so use the @ideal-postcodes/react component. It renders its own <input>, attaches the widget, and hands the selected address back through onAddressRetrieved: no <script> tags, useEffect loaders, CSS selectors, or controlled/uncontrolled juggling. The one thing left to get right is delivering the API key from a Saved Secret to the browser. The rules below cover both.

Install the package​

  • Install @ideal-postcodes/react and import the component: import { AddressFinder } from "@ideal-postcodes/react";. It pulls in @ideal-postcodes/address-finder automatically. Do not inject a <script> tag in JSX. React does not execute script tags rendered that way, and you don't need one: import the component from npm.

Wiring the widget​

  • Render the component and read the resolved address from onAddressRetrieved:

    import { AddressFinder } from "@ideal-postcodes/react";

    <AddressFinder
      apiKey={apiKey}
      onAddressRetrieved={(address) => {
        setForm({
          line_1: address.line_1,
          line_2: address.line_2,
          line_3: address.line_3,
          post_town: address.post_town,
          postcode: address.postcode,
          country: address.country,
        });
      }}
    />

  • The component draws its own search <input>. To reuse a styled input, pass it as a single child instead (wrap mode): <AddressFinder apiKey={apiKey} ...><input className="..." /></AddressFinder>.

  • Populate every other field from the onAddressRetrieved callback into React state. Those fields are controlled (value + onChange) as normal; the component never writes to them directly.

  • The stylesheet is auto-injected by default (injectStyle defaults to true), so the dropdown is styled out of the box. No separate CSS import is required.

API key​

  • Add a backend function at web/api/idpc-config/route.ts that reads the IDEAL_POSTCODES_API_KEY Saved Secret and returns it to the frontend. Fetch it on mount into state and pass it as the apiKey prop. Render <AddressFinder> only once the key has arrived. Do not hardcode the key.

Errors​

  • Pass onSearchError and onSuggestionError props. If the Ideal Postcodes API returns a 4xx error, surface the error's message to the user. Do not swallow it.

Reference docs​