Autofill from a lookup

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.

View as Markdown

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)
  • A trigger — onFieldBlur (or onFieldChange, onStepEnter) decides when it runs
  • mapResponse — target field → path in the answer (a.b.0.c)

Type 28001, 08001 or 41001 and leave the postcode field: city and province fill in. Any other code finds nothing and leaves the form alone. The answers are static JSON files served with this page.

Try 28001, 08001 or 41001

Type 28001 and leave the field…
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:

.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.