Autofill from a lookup
What it combines
- The
lookupsubmit action — a GET to a JSON endpoint, with{{field}}placeholders, whose answer is copied into other fields (Submit & Actions) - A trigger —
onFieldBlur(oronFieldChange,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.
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}}inendpointorparamsis 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
disabledwitharia-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:
endpointandparamscannot 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 pasttimeoutMs. - Placeholder position —
{{field}}cannot sit in the host of the URL. - Not every trigger — only
onFieldBlur,onFieldChangeandonStepEnterare 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
onFieldChangeto look up while the visitor types: the trigger waitsdebounceMsof silence before it asks, so set it to suit the endpoint.onStepEnterwith astepIdto prefill a step from an earlier answer.params: { country: '{{country}}' }for query-string parameters.