# Autofill from a lookup

URL: https://docs.forms.saastro.io/docs/recipes/lookup-autofill
> Fill city and province from a postcode with the lookup submit action, which queries a JSON endpoint in the browser and copies parts of the answer into other fields.

# Autofill from a lookup

## What it combines

- **The `lookup` submit action** — a GET to a JSON endpoint, with `{{field}}` placeholders, whose answer is copied into other fields ([Submit & Actions](/docs/submit))
- **A trigger** — `onFieldBlur` (or `onFieldChange`, `onStepEnter`) decides when it runs
- **`mapResponse`** — target field → path in the answer (`a.b.0.c`)

```tsx
import { FormBuilder } from '@saastro/forms';

/**
 * Postcode → city and province. A `lookup` action runs in the browser when the visitor leaves
 * the postcode field: it GETs the endpoint (`{{postal}}` is replaced by the typed value) and
 * copies parts of the JSON answer into other fields, which stay editable.
 */
export function createConfig({ base = '' }: { base?: string } = {}) {
  return FormBuilder.create('lookup-autofill')
    .layout('manual')
    .columns(12)
    .addField('postal', (f) =>
      f
        .type('text')
        .label('Postcode')
        .helperText('Try 28001, 08001 or 41001')
        .required()
        .columns({ default: 12, md: 4 }),
    )
    .addField('city', (f) => f.type('text').label('City').required().columns({ default: 12, md: 4 }))
    .addField('province', (f) =>
      f.type('text').label('Province').required().columns({ default: 12, md: 4 }),
    )
    .addStep('address', ['postal', 'city', 'province'])
    .initialStep('address')
    .submitAction(
      'postal-lookup',
      {
        type: 'lookup',
        name: 'Postcode lookup',
        endpoint: `${base}/demo/postal/{{postal}}.json`,
        // target field → path in the JSON answer
        mapResponse: { city: 'city', province: 'province' },
        timeoutMs: 3000,
        onError: 'ignore',
      },
      { type: 'onFieldBlur', fieldName: 'postal' },
    )
    .build();
}
```

## The code

The **Code** tab above is the whole form. The action is one call:

```ts
.submitAction(
  'postal-lookup',
  {
    type: 'lookup',
    name: 'Postcode lookup',
    endpoint: '/api/postal/{{postal}}',
    mapResponse: { city: 'city', province: 'province' },
  },
  { type: 'onFieldBlur', fieldName: 'postal' },
)
```

## How it works

- **No value, no request** — if a `{{field}}` in `endpoint` or `params` is empty, nothing is sent.
- **The visitor keeps control** — the copied values land in ordinary fields that can be edited.
- **While a lookup is running**, Next and Submit are `disabled` with `aria-busy`, so the form cannot be sent half filled.
- **It gives up quietly** — after `timeoutMs` (default 5000) the request is abandoned and the form continues. `onError: 'ignore'` (default) leaves the fields as they were; `'clear'` empties the targets.
- **Only scalars are copied** — text, numbers and booleans. Objects and arrays in the answer are skipped.

## Caveats

- **Client only** — the server, the Hub and the submit orchestrator never run a `lookup`. Validate what arrives anyway.
- **It runs in the browser**: `endpoint` and `params` cannot carry secrets (an API key in the URL is public), and the endpoint must allow your origin (CORS). Put a proxy of your own in front of a keyed API.
- **Size and time limits** — the answer is capped at `maxBytes` (default 65,536) and abandoned past `timeoutMs`.
- **Placeholder position** — `{{field}}` cannot sit in the host of the URL.
- **Not every trigger** — only `onFieldBlur`, `onFieldChange` and `onStepEnter` are accepted.
- **A wrong lookup is silent** — with `onError: 'ignore'` a failed request looks like "nothing happened". Keep the target fields editable and required so the visitor can finish.

## Variations

- `onFieldChange` to look up while the visitor types: the trigger waits `debounceMs` of silence before it asks, so set it to suit the endpoint.
- `onStepEnter` with a `stepId` to prefill a step from an earlier answer.
- `params: { country: '{{country}}' }` for query-string parameters.

## Related

- [Submit & Actions](/docs/submit)
- [Cascading selects](/docs/recipes/cascading-selects)
- [Validate the same rules on the server](/docs/recipes/server-validation)
