Reference

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.search once with URLSearchParams.
  • For each distinct key, calls setValue once. 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 fieldName is 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 input event, so watchers and subscribers fire.
  • Triggers validation if it has rules and autoValidate is 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-error attributes.

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

  • window must exist. The browser bundle uses window.location; in non-DOM environments prefill is 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 because URLSearchParams.forEach visits both entries; the second setValue call overwrites the first.
  • Prefill runs synchronously. Call it after the form is in the DOM.
  • 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.