Prefill & hidden fields

URL prefill

URL prefill works in embeds automatically (SDK 0.6+), not just on the hosted /f page. After hydration the SDK reads the page’s query string. Supported fields use ?fieldId=value; hidden fields read their configured paramName (falling back to the field id).

Supported URL values follow the live parser rules:

• Short text, long text, email, URL, phone, date, and hidden fields: Use the parameter value as text. Visible fields still go through normal validation before submission.
• Number fields: Accept plain decimal values within the configured minimum and maximum. Exponents, hexadecimal values, and non-finite numbers are ignored.
• Rating and linear scale fields: Accept whole numbers within the field's configured range.
• Checkbox fields: Treat true, 1, and yes as checked. Any other non-empty value is unchecked.
• Select and dropdown fields: Accept an exact option ID and ignore values that are not configured options.
• Multi-select fields: Accept comma-separated exact option IDs without added spaces. Unknown IDs and duplicates are discarded, and at least one valid option must remain.

Empty parameter values are ignored. Choice and numeric values outside the schema are also ignored. Visible text-like values still go through normal form validation before submission. file_upload, ranking, matrix, signature, custom, calculated fields are never prefilled from a URL.

initialData

Precedence: an explicit initialData prop and anything the visitor already typed win over URL parameters.

"use client";

import { FilloForm } from "@usefillo/react";

export function Onboarding({ userEmail }: { userEmail: string }) {
  // initialData wins over URL parameters; visitors can still edit the values.
  return <FilloForm formId="onboarding" initialData={{ email: userEmail, plan: "team" }} />;
}

Manual parsing

Defaults: hidden fields may carry a defaultValue, applied when no matching parameter is present. Other field kinds don’t take defaultValue. Schema normalization strips it, so use initialData for visible fields. For manual control, @usefillo/core exports the parser itself:

import { defineForm, prefillFromParams } from "@usefillo/core";

const form = defineForm({
  id: "waitlist",
  pages: [{ id: "p1", blocks: [
    { id: "email", kind: "email", label: "Email", required: true },
    { id: "src", kind: "hidden", label: "Source", paramName: "src", defaultValue: "direct" },
  ]}],
});

// The exact parser the SDK runs after hydration. Call it yourself when you
// want the values earlier, or somewhere without a URL:
const params = Object.fromEntries(new URLSearchParams("?email=ada@example.com&src=newsletter"));
const initialData = prefillFromParams(form.schema, params);
// Result: { email: "ada@example.com", src: "newsletter" }, coerced and validated per kind