- Docs
- Fill fields from the URL with prefill()
Fill fields from the URL with prefill()
Populates the form or one field from the URL query string. Repeated keys become arrays, and auto-submit runs once after the batch.
Populates the form (or a single field) from the current URL query string. Useful for sharing prefilled links, marketing tracking params, or restoring form state from location.search.
Signature
prefill(): FormController
prefill(fieldName: string): FormController
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
fieldName |
string |
no | When provided, only this field is prefilled. When omitted, every query parameter is matched. |
Returns
The same FormController — chainable.
Behaviour
- Reads
window.location.searchonce withURLSearchParams. - For each distinct key, calls
setValueonce. A key that appears several times (?tags[]=new&tags[]=sale) is written as an array, so every matching checkbox or repeated input is filled (since 2.8.0; earlier versions kept only the last value). - When
fieldNameis provided, only the matching key is written. - Values are always strings. If a field expects a different shape (e.g.
number), the consumer must convert.
Because the method delegates to setValue, each prefilled field:
- Receives a synthetic
inputevent, so watchers and subscribers fire. - Triggers validation if it has rules and
autoValidateis enabled. - Triggers autoSubmit if it is enabled — once for the whole prefill, not once per field (since 2.8.0).
- Updates the
css-filled/css-errorattributes.
Examples
Prefill the whole form
import { form } from '@samline/forms'
// URL: https://example.com/contact?utm_source=newsletter&email=hi@example.com
const contact = form('contact-form')
contact.prefill()
contact.getValue('email') // 'hi@example.com'
contact.getValue('utm_source') // 'newsletter'
Prefill a single field
const contact = form('contact-form')
contact.prefill('email')
Round-trip a draft through the URL
import { form } from '@samline/forms'
const draft = form('draft-form')
// User types into fields, watchers debounce-serialize and push to the URL:
draft.subscribe(state => {
const params = new URLSearchParams()
for (const [key, value] of Object.entries(state.values)) {
if (typeof value === 'string') params.set(key, value)
}
history.replaceState(null, '', `?${params.toString()}`)
})
// On next mount:
draft.prefill()
Edge cases
windowmust exist. The browser bundle useswindow.location; in non-DOM environmentsprefillis a no-op.- Values are always strings. Prefilling a
<select>requires the query value to match one of the option values exactly. - Repeated query keys (
?tag=a&tag=b) are processed in iteration order. Only the last value wins becauseURLSearchParams.forEachvisits both entries; the secondsetValuecall overwrites the first. - Prefill runs synchronously. Call it after the form is in the DOM.
Related
setValue— underlying primitive.getValue— read the prefilled values.format— when a field is formatted, prefilling the canonical name writes the raw and reformats the visible; prefilling the display name writes the formatted and recomputes the raw. See the mirror convention.