/wix-headless

RECIPE: How to Code a Wix Forms Frontend (@wix/forms, Form Submissions v4)

A concise contract for writing the frontend code that renders a seeded form and submits it: reading the live schema to build the inputs, collecting the values, and creating a submission. This recipe is the how (which modules, which calls), not the what — which forms to render, how the page looks, and the framework are decided by the request you're fulfilling.

This recipe is for CODING the frontend, not for seeding it. It assumes the form schema already exists (created by setup-forms.md) — you have each form's formId (and its field targets) from the seed's seeded.forms map. The field set, order, labels, required, validation format, and dropdown options are read live from the schema at render time (see "Rendering" below). It says nothing about creating forms — only how to read, render, and submit them from frontend code.

Render schema-driven by default — read the schema and generate the inputs. This is the standard path for every forms site and what this section documents: an owner edit in the Wix dashboard reflects on the site with no code change, and the submit map can never desync from the schema. A dropdown, non-trivial validation, or several forms on one site are not reasons to hardcode — those are exactly what the schema carries, so hardcoding them is strictly more code and more drift. Each form simply reads its own schema by formId.

The ONLY exception is a brief that is explicitly design-led — the visual design is the whole point, the form is a small fixed part of a hand-crafted layout, and dashboard-editability is explicitly not a goal (e.g. the inquiry-design wedding-photographer brief). There you may hardcode <input name="<target>">, but read the actual targets from the schema — never guess or derive them from labels: a key that isn't an exact schema target 400s the whole submission.

⚠️ Reading rule — always append ?apiView=SDK to every doc link below. The Wix docs render two views of the same page. The bare / REST view shows the wrapped REST body ({ submission: {…} }) and an id field; the ?apiView=SDK view shows the SDK call (submissions.createSubmission(submission, options)) and the normalized _id field. The SDK is what your frontend calls; reading the REST view leads to the wrong call signature and the id-vs-_id trap.

The module and the client (read this first)

⚠️ Two modules of @wix/forms, both used from the frontend:

• forms — reads the form schema to render fields: import { forms } from "@wix/forms", then forms.getForm(formId) / forms.queryForms(query) / forms.listForms(namespace).
• submissions — writes a submission: import { submissions } from "@wix/forms", then submissions.createSubmission(submission, options).

(The frontend reads schemas and writes submissions; it never creates schemas — that's the seed.)

⚠️ CRITICAL: a plain anonymous visitor token reads the form schema — NO auth.elevate, no backend, no owner creds. forms.getForm(formId) / forms.listForms("wix.form_app.form") return 200 with the full schema (all formFields[] with identifier + inputOptions.target + the stringOptions.validation/componentType/options blocks, the steps layout, submitSettings) on the same visitor client that submits. This contradicts the docs: the API spec lists every read method (getForm/queryForms/listForms/getFormSummary) as requiring the owner scope WIX_FORMS.FORM_SCHEMA_READ ("Manage Submissions"), and every SDK example ships an "(with elevated permissions)" variant. Trust the live 200, not the permission table — Wix grants implicit visitor read for published-site rendering. Do NOT add auth.elevate to the read — it is unnecessary, and a pure SPA/static frontend can't elevate anyway and doesn't need to. Schema-driven rendering is therefore universal — every framework, including a pure static SPA, with no server or proxy.

Submissions read-back stays owner-only. Only the schema read is visitor-accessible. Reading submissions back (querySubmissionsByNamespace, getSubmission, countSubmission) requires the owner permission WIX_FORMS.SUBMISSION_READ_ANY and is not available to a visitor — don't try to list/confirm submissions from the frontend. The submit's resolved promise is your success signal (show a thank-you); the submission lands in the site owner's dashboard.

Auth / client — framework split (the SAME client both reads the schema and submits — no elevate on either):

• Astro (Wix-managed): authentication is ambient. Call forms.getForm(...) / forms.listForms(...) in the page frontmatter / a server route, and submissions.createSubmission(...) from a server route (src/pages/api/*.ts) or a server action — no createClient, no OAuthStrategy, no clientId, no auth.elevate. (The schema read can equally run client-side; server-side in SSR is simplest so the fields are in the initial HTML.)
• Non-Astro (Vite/React/Vue/static): build one manual visitor client with both modules and reuse it — the read runs client-side, no server needed:

  import { createClient, OAuthStrategy } from '@wix/sdk';
  import { forms, submissions } from '@wix/forms';
  
  const client = createClient({
    modules: { forms, submissions },
    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
  });
  // read to render:  client.forms.getForm(formId)
  // then submit:     client.submissions.createSubmission(submission)

  The clientId is public, not a secret.

⚠️ CRITICAL: do NOT call auth.elevate to submit. An anonymous visitor can create a submission on the plain visitor token (it stamps submitter.visitorId). A pure SPA/static frontend has no server and cannot elevate anyway. (The Velo docs example wraps createSubmission in auth.elevate inside a backend web.js — that's the Velo hosted pattern, not the headless visitor path; ignore it here.)

The features (build the ones the site needs)

A forms frontend is essentially one feature — render the fields, then submit — plus the render/validation details around it. Implement it once per form the site shows.

Rendering the inputs (read the schema, then bind name = target)

Read the live schema, project its formFields into a render model, and generate one input per field. The field's target (at inputOptions.target — the immutable lowercase snake_case key the seed authored, e.g. first_name, message) becomes the input's name — it's the contract the submission must use. Because the inputs are generated from the schema, the field set, order, labels, required, validation format, length/pattern constraints, and dropdown options all track the dashboard: a field the owner adds/removes/relabels — or a constraint they tighten — reflects on the site with no code change.

1 · Fetch the schema (visitor token, no elevate). Fetch by id when you have it (the handoff carries formId), else discover by namespace. Note the return shapes differ: getForm resolves to the Form directly, while listForms resolves to { forms }.

import { forms } from '@wix/forms';   // Astro: call directly. Non-Astro: client.forms

// ONE form → getForm resolves to the Form directly (not `{ form }`-wrapped)
const form = await forms.getForm(SEEDED_FORM_ID);          // from seeded.forms[].formId

// SEVERAL forms on a page → ONE listForms call, not one getForm each.
// Signature is listForms(namespace, options); `formIds` takes up to 100 ids.
const { forms: list } = await forms.listForms('wix.form_app.form', { formIds: SEEDED_FORM_IDS });

// No ids to hand? Discover every form in the namespace:
const { forms: all } = await forms.listForms('wix.form_app.form');

listForms returns only enabled forms by default — usually what you want on a public site, but it does mean a form the owner disabled silently vanishes from a discovery listing rather than erroring.

2 · Project form.formFields into a render model.

// Display order comes from steps[], not from formFields[] (About Form Fields, "Field order comes
// from the layout") — including the breakpoint fallback below.
const order = new Map(
  (form.steps ?? [])
    .flatMap((s) => s.layout?.large?.items ?? s.layout?.medium?.items ?? s.layout?.small?.items ?? [])
    .sort((a, b) => (a.row - b.row) || (a.column - b.column))
    .map((item, i) => [item.fieldId, i]),
);

const camel = (e) => (e ?? '').toLowerCase().replace(/_(.)/g, (_, c) => c.toUpperCase());

// The input types THIS renderer handles. BOOLEAN (checkbox), WIX_FILE (file upload / signature),
// PAYMENT and SCHEDULING need their own controls — a checkbox's label is a Ricos rich-content
// OBJECT, not a string, so letting one fall through to the text branch prints `[object Object]`
// (or throws in React). Skip them explicitly; add a branch when a brief needs one.
// ⚠️ A skipped field that is `required` makes the form UNSUBMITTABLE (the server will demand it), so
// log that case loudly and write the branch — a consent CHECKBOX is the one you'll hit first.
const RENDERABLE = new Set(['STRING', 'NUMBER', 'ARRAY', 'ADDRESS']);

const inputs = (form.formFields ?? [])
  .filter((f) => f.fieldType === 'INPUT' && !f.hidden   // the submit button is fieldType: 'DISPLAY'
    && RENDERABLE.has(f.inputOptions?.inputType))
  .map((f) => {
    const io = f.inputOptions ?? {};
    // ONE naming rule for BOTH nesting levels (About Form Fields, "How a field is composed"):
    // camelCase the enum value and append `Options` — `inputType` names the outer block,
    // `componentType` the sub-block inside it. DERIVE both; a hardcoded `??` chain of block names
    // silently misses types (TIME_INPUT, DATE_TIME, RATING_INPUT, …) and reads back no label.
    const to = io[`${camel(io.inputType)}Options`] ?? {};        // stringOptions / arrayOptions / …
    const comp = to[`${camel(to.componentType)}Options`] ?? {};  // textInputOptions / dropdownOptions / …
    const val = to.validation ?? {};
    return {
      id: f.id,                                          // used only to order by steps[] below
      target: io.target,                                 // → input `name` (THE submission key)
      inputType: io.inputType,
      label: comp.label ?? io.target,
      placeholder: comp.placeholder ?? '',
      defaultValue: comp.default,                        // owner-set prefill; undefined → none
      required: io.required ?? false,                    // NOTE: on inputOptions, not inside validation
      format: val.format,                                // EMAIL | PHONE | URL | UNKNOWN_FORMAT | …
      minLength: val.minLength,                          // owner-set length/pattern constraints —
      maxLength: val.maxLength,                          // carry them so the client validates them too,
      pattern: val.pattern,                              // not just the server (see "validation" below)
      identifier: f.identifier,                          // per the field table in About Form Fields
      componentType: to.componentType,
      multiple: io.inputType === 'ARRAY',                // multi-choice → submits an ARRAY
      options: comp.options?.map((o) => ({ value: o.value, label: o.label ?? o.value })),
      // PHONE may narrow or preselect the country (both ISO-3166 alpha-2):
      allowedCountryCodes: val.phoneOptions?.allowedCountryCodes,
      defaultCountryCode: comp.defaultCountryCode,
      // ADDRESS fields submit a NESTED OBJECT, not a string. validation.fields lists the subfields
      // and their required-ness; only addressLine2 has a visibility setting, so the filter below
      // hides just that one. `false` for every non-address field.
      addressParts: io.inputType === 'ADDRESS' && Object.entries(val.fields ?? {})
        .filter(([sub]) => comp.fieldSettings?.[sub]?.show !== false)
        .map(([sub, cfg]) => ({ sub, required: cfg?.required ?? false })),
      allowedCountries: val.allowedCountries,            // ADDRESS: narrows the country <select>
    };
  })
  // A field the owner never placed in the layout sorts LAST, not first — it still stores values.
  .sort((a, b) => (order.get(a.id) ?? Infinity) - (order.get(b.id) ?? Infinity));

About Form Fields documents which identifier pairs with which component, which options block each combination nests in, and what each field submits — read it rather than guessing a block name. A number, address or multi-choice field's format/minLength come back undefined: those constraints exist only on a STRING field's validation.

⚠️ Two paths the projection gets wrong most often: required is at inputOptions.required, not inside the validation block; and unconstrained text reads back as UNKNOWN_FORMAT, so never test for UNDEFINED.

3 · Render inputs.map(...), deriving the control from the projected model — a dropdown is signalled by componentType, a textarea by identifier, the input type by format:

inputs.map((field) => {
  // Address (MULTILINE_ADDRESS) → a GROUP of sub-inputs; its submission value is an OBJECT.
  // Name each sub-input `${target}/${sub}` — that is EXACTLY the server's error path for a nested
  // field (e.g. "address/subdivision"), so the submit step nests them back AND a per-subfield
  // server error maps straight onto the right control (see "Submitting" and the error mapping below).
  // NB: `country` and `subdivision` are country-dependent enums, not free text (see the ⚠️ note) —
  // render `country` as a <select> (your own, over an ISO-3166 alpha-2 list, narrowed to
  // field.allowedCountries when that's non-empty) rather than a free-text input.
  if (field.addressParts) {
    return (
      <fieldset key={field.target}>
        <legend>{field.label}{field.required && ' *'}</legend>
        {field.addressParts.map(({ sub, required }) => {
          const name = `${field.target}/${sub}`;            // == the server errorPath for this subfield
          return (
            <label key={sub}>{sub}{required && ' *'}         {/* humanize `sub` for display as you like */}
              {sub === 'country'
                ? <CountrySelect name={name} required={required} allowed={field.allowedCountries} />
                : <input name={name} required={required} />}
              {fieldErrors[name] && <small className="field-error">{fieldErrors[name]}</small>}
            </label>
          );
        })}
      </fieldset>
    );
  }
  // Radio group (single choice) → radios sharing name=target; submits a single string
  if (field.componentType === 'RADIO_GROUP') {
    return (
      <fieldset key={field.target}><legend>{field.label}{field.required && ' *'}</legend>
        {field.options.map((o) => (
          <label key={o.value}><input type="radio" name={field.target} value={o.value}
            defaultChecked={o.value === field.defaultValue} required={field.required} /> {o.label}</label>
        ))}
      </fieldset>
    );
  }
  // Checkbox group (multi choice, inputType ARRAY) → checkboxes sharing name=target; submits an ARRAY
  if (field.multiple) {
    return (
      <fieldset key={field.target}><legend>{field.label}{field.required && ' *'}</legend>
        {field.options.map((o) => (
          <label key={o.value}><input type="checkbox" name={field.target} value={o.value} /> {o.label}</label>
        ))}
      </fieldset>
    );
  }
  // Dropdown → <select> — a single-choice STRING field
  if (field.componentType === 'DROPDOWN') {
    return (
      <label key={field.target}>{field.label}{field.required && ' *'}
        <select name={field.target} required={field.required} defaultValue={field.defaultValue ?? ''}>
          <option value="" disabled>{field.placeholder || 'Select…'}</option>
          {field.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
        </select>
      </label>
    );
  }
  // Textarea — detected by `identifier` (see gotcha below), NEVER by componentType
  if (field.identifier === 'TEXT_AREA') {
    return (
      <label key={field.target}>{field.label}{field.required && ' *'}
        <textarea name={field.target} required={field.required} rows={4} defaultValue={field.defaultValue}
          minLength={field.minLength} maxLength={field.maxLength} />
      </label>
    );
  }
  // Text/date input — derive `type` from the validation format; stamp the schema's constraints.
  // DATE_INPUT and DATE_PICKER are both format 'DATE' → <input type="date"> (submits a date string).
  const type =
    field.componentType === 'NUMBER_INPUT' ? 'number' :  // NUMBER field — no format; empty validation
    field.format === 'EMAIL' ? 'email' :
    field.format === 'PHONE' ? 'tel' :
    field.format === 'URL' ? 'url' :
    field.format === 'DATE' ? 'date' :
    field.format === 'TIME' ? 'time' :
    field.format === 'DATE_TIME' ? 'datetime-local' : 'text';
  // inputMode picks the right on-screen keyboard on mobile; undefined → attribute omitted
  // (date/time use the native picker, so no inputMode).
  const inputMode =
    type === 'number' ? 'decimal' :
    type === 'tel' ? 'tel' :
    type === 'email' ? 'email' :
    type === 'url' ? 'url' : undefined;
  // `defaultValue` is the owner's prefill from the schema — dropping it loses a dashboard setting.
  return (
    <label key={field.target}>{field.label}{field.required && ' *'}
      <input name={field.target} type={type} inputMode={inputMode} required={field.required}
        defaultValue={field.defaultValue} placeholder={field.placeholder}
        minLength={field.minLength} maxLength={field.maxLength} pattern={field.pattern} />
    </label>
  );
});

Show the expected shape in the placeholder, not a second line of copy. format tells you what a constrained field wants, so surface an example up front — but reuse the placeholder the render already passes rather than adding a separate hint element that just duplicates the inline error. When the schema's placeholder is empty for a constrained field, synthesize one from format (PHONE → phoneExample(field), the reserved example for the field's own country — see PHONE_EXAMPLE under Validation; URL → https://…). The example prevents the must match format "phone" error without a redundant help line under every field.

⚠️ Detection signals — identifier and componentType are INDEPENDENT axes, because several fields share one general-purpose component (About Form Fields, "Some component types serve several fields"). Switch on whichever axis distinguishes the control you are rendering — and never on the target name: a rename silently breaks name-based detection, while identifier and componentType stay authoritative. Three that bite in practice:

• <textarea> → identifier === "TEXT_AREA". componentType is TEXT_INPUT for short and long answer, so keying off it renders every long-text field single-line.
• country / subdivision are country-dependent enums the schema does not enumerate, so a plain <input> invites a rejection. Render country as a <select> (narrowed to allowedCountries when non-empty) and, ideally, subdivision as a country-dependent <select> from an ISO-3166-2 / Wix subdivision dataset. If you must keep them text, leave subdivision optional and rely on the mapped inline error.
• IMAGE_CHOICE looks exactly like multi-choice (ARRAY + CHECKBOX_GROUP), so it renders as plain checkboxes here. Only identifier distinguishes it — branch on that if the brief wants the images.

Validation — schema-driven on the client, authoritative on the server

The schema carries the validation rules too: required, the format (EMAIL/PHONE/URL), and minLength/maxLength/pattern. Two layers, and the split matters:

Server (authoritative). createSubmission enforces the field's validation block server-side. Any violation — missing required, bad email, too short/long, pattern mismatch — comes back under err.details.validationError.fieldViolations[] with an errorPath and an errorType. You must map these back to per-input errors (see the mapping in "Submitting"); this is the backstop that always holds even if a rule is missed client-side.

Client (schema-driven UX). Pre-validate from the same projected constraints so the user gets inline feedback before a round-trip — and derive every check from the schema, never from the field name. ⚠️ The common mistake (seen in practice) is keying the email check on target === "email"; do it off format so an owner-added PHONE/URL/length rule is honored with no code change:

⚠️ No user-visible example value may be hardcoded to one locale. Phone, postcode/ZIP, currency, date or address examples in placeholders, hint text and error copy all derive from the site's country — a +44- or US-only example shipped to every site is a locale bug, not a default. And an illustrative phone number must come from that country's regulator-reserved fictional range, never a plausible-looking one: a real number risks reaching a real person.

Resolve SITE_COUNTRY once (ISO-3166 alpha-2), in this order, and reuse it:

1. the site context you already hold, if the run fetched one — sites[].properties.locale.country;
2. else the Site Properties API — GET https://www.wixapis.com/site-properties/v4/properties → properties.locale.country (SDK: @wix/business-tools siteProperties.getSiteProperties());
3. else infer from the brief (a stated location, an address, a phone dialling code);
4. else default US.

// Phone example shown to visitors (placeholder + error copy), derived from SITE_COUNTRY — NEVER
// hardcoded to one locale. Every value is a regulator-RESERVED fictional number for that country, so
// no real subscriber is ever printed — and being display-only it needn't pass Wix's E.164 check
// (submitting one would 400; see the sidebar). Add a market only after verifying its reserved range
// in the national numbering plan — never invent a number.
const PHONE_EXAMPLE = {
  US: '+1 201 555 0123', CA: '+1 416 555 0123', // NANP 555-0100–0199 reserved for fiction
  GB: '+44 7700 900123',                         // Ofcom drama range 07700 900xxx
  IE: '+353 20 910 0001',                        // ComReg reserved 020 91x xxxx
  AU: '+61 491 570 006',                         // ACMA reserved mobile range
  FR: '+33 1 99 00 00 01',                       // ARCEP Île-de-France 01 99 00 xx xx reserved
  DE: '+49 30 23125 000',                        // BNetzA Berlin 030 23125 xxx reserved
  SE: '+46 70 174 06 05',                        // PTS reserved 070 174 06xx
  KR: '+82 2 540 0000',                          // Seoul 02-540-xxxx reserved
};
// A PHONE field may narrow or preselect its country (`allowedCountryCodes` / `defaultCountryCode`,
// both projected above). Prefer the FIELD's country over the site's, so the example shown is one the
// field would actually accept; fall back to the site's, then to US (the default above).
const phoneCountry = (field) =>
  field.defaultCountryCode ?? field.allowedCountryCodes?.[0] ?? SITE_COUNTRY;
const phoneExample = (field) => PHONE_EXAMPLE[phoneCountry(field)] ?? PHONE_EXAMPLE.US;

function fieldError(field, raw) {
  const v = (raw ?? '').trim();
  if (field.required && !v) return `${field.label} is required.`;
  if (!v) return '';                                              // optional + empty → ok
  if (field.minLength && v.length < field.minLength) return `${field.label} must be at least ${field.minLength} characters.`;
  if (field.maxLength && v.length > field.maxLength) return `${field.label} must be at most ${field.maxLength} characters.`;
  if (field.format === 'EMAIL' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)) return 'Please enter a valid email address.';
  if (field.format === 'URL'   && !/^https?:\/\/.+/.test(v)) return 'Please enter a valid URL.';
  // PHONE is E.164 server-side: leading +, country code, digits only. Strip formatting first —
  // visitors add spaces, dashes and parens, and rejecting those is a UX bug, not validation.
  // Submit the NORMALIZED value, not the raw one.
  const phone = v.replace(/[\s()\-.]/g, '');
  if (field.format === 'PHONE' && !/^\+[1-9]\d{6,14}$/.test(phone))
    return `Use international format, e.g. ${phoneExample(field)}.`;
  if (field.pattern && !new RegExp(field.pattern).test(v)) return `${field.label} is not in the expected format.`;
  return '';
}

⚠️ A client check that is laxer than the server's is worse than none — it guarantees the visitor learns about the problem only after a round trip, in the server's wording rather than yours. Every rule here must be at least as strict as the server's, and the value you submit must be the normalized one the check passed.

Run it over the projected inputs on submit (and on blur — see UX below); block the submit if any returns non-empty. The <input>/<textarea> also carry minLength/maxLength/pattern and (for text) the format-derived type from the render step, so native constraints reinforce the JS checks. Don't hardcode a fixed field list or a per-field rule — both the render and the validation read the live schema, so a dashboard-added constraint (a new maxLength, a stricter pattern) takes effect on the site with no code change.

PHONE is E.164, validated in two layers. First the shape — leading +, country code, digits only; spaces, dashes, parens and a national leading 0 all fail with must match format "phone". Then a per-country length/prefix check — +99889899889 returns Phone number for the country code provided is invalid. A number in a country's reserved range — including the fictional example we show — is rejected with the misleading Phone number's country code must correspond to one from allowed countries; the country is fine, the number isn't. An allow-list does exist (validation.phoneOptions.allowedCountryCodes, projected as allowedCountryCodes), but it is not what fires here — widening or clearing it won't help. Never submit the example: it's display-only.

Take only the ORDER from steps[], not the geometry — width, multi-column and multi-page are a Phase-2 concern the frontend's own layout replaces.

Submitting (create a submission)

Collect the input values into a submissions object keyed by target, and call createSubmission. Doc: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission?apiView=SDK

import { submissions } from '@wix/forms';   // Astro: call directly. Non-Astro: client.submissions

async function submitContact(formEl) {
  // Flat fields land as `target` → value. Address sub-inputs are named `target/sub`, so fold any
  // slashed key back into a nested object — the shape an ADDRESS field's `target` expects.
  const arrayTargets = new Set(inputs.filter((f) => f.multiple).map((f) => f.target)); // multi-choice targets
  const values = {};
  for (const [name, value] of new FormData(formEl)) {
    const slash = name.indexOf('/');                               // address sub-inputs are `target/sub`
    if (slash !== -1) { (values[name.slice(0, slash)] ??= {})[name.slice(slash + 1)] = value; continue; } // → { sub: value }
    if (arrayTargets.has(name)) (values[name] ??= []).push(value); // multi-choice → ARRAY of checked values
    else values[name] = value;                                     // single value: text / dropdown / radio / …
  }
  const { _id, status } = await submissions.createSubmission({
    formId: SEEDED_FORM_ID,          // from seeded.forms[].formId
    submissions: values,             // map of target -> value (or -> nested object, for an address)
  });
  return { _id, status };            // any status → the submission exists; render a thank-you (see the status note below)
}

⚠️ CRITICAL: createSubmission takes POSITIONAL args — createSubmission(submission, options), NOT createSubmission({ submission }). The first argument is the submission object ({ formId, submissions }) directly; the optional second argument is options (e.g. captchaToken). Wrapping it as { submission: {…} } is the REST body shape and does not type-check against the SDK.

The submissions map is keyed by each field's target — see About Submission Values for the keys and the per-inputType value shapes. This is why the render step binds name = target from the projected schema: collecting FormData then yields the right keys by construction, with no hand-maintained list to drift.

⚠️ Two rejections that are SEED bugs, not frontend bugs — don't mangle the frontend key or value:

• An UNKNOWN_VALUE_ERROR on a key that is in the schema means the field was seeded without a validation block, and that block is what registers the target as an accepted value (About Form Fields, "Validation"). It only surfaces once someone actually fills that field in, since an empty value is dropped before validation.
• A NOT_ALLOWED_VALUE_ERROR on a choice field means the seed's options[].value and its validation enum disagree — the two declarations must match (About Form Fields, "Choice fields").

Both are fixed in setup-forms.md STEP 2.

⚠️ Read status from the result — but a resolved call means the submission EXISTS, whatever the status. For the Wix Forms namespace it's CONFIRMED (recorded). Some namespaces return PENDING, which is not yet recorded in the Wix Forms collection but is a created submission; PAYMENT_WAITING is a created submission on a form that collects payment (Submission status).

All three are a successful submit — show the thank-you. The visitor has done everything the form asked of them; confirming a PENDING is a server-side step they play no part in. Showing an error instead invites them to submit again, so the cost of getting this wrong is duplicate submissions in the owner's inbox for a submission that already exists.

PAYMENT_WAITING is the same call: the entry is in the owner's inbox and the submit succeeded, so never fail it back to the visitor. Payment is a separate step — surface it inside the success state (a "complete your payment" link or instruction) rather than as a failed submission. Since this renderer skips PAYMENT fields it shouldn't arise at all; if it does, the schema has a payment field the UI isn't rendering.

const { _id, status } = await submissions.createSubmission({ formId, submissions: values });
// CONFIRMED | PENDING | PAYMENT_WAITING → the submission exists. Thank-you either way.
if (status === "PAYMENT_WAITING") { /* …and surface the payment step within it */ }

⚠️ Per-field validation errors — the SDK buries them two levels deeper than the docs' shape. The documented entries (errorPath, errorType, errorMessage, params — see Validation errors) arrive under err.details.validationError.fieldViolations[], each with its own data.errors[] array. Flatten that and name each input by its errorPath so the message lands on the right control instead of only a form-level banner — that is why the address render names its sub-inputs ${target}/${sub}, matching the server's own nested path. Then write every message from errorType plus the field's projected schema (label, format, minLength/maxLength); the docs' rule against showing errorMessage is hard here — it goes to console.debug only:

const FORMAT_COPY = {           // used for FORMAT_ERROR, keyed by the field's validation format
  EMAIL: () => 'Enter a valid email address.',
  PHONE: (f) => `Use international format, e.g. ${phoneExample(f)}.`,  // field/site-derived country
  URL:   () => 'Enter a full URL starting with https://',
  DATE:  () => 'Choose a valid date.',
};
const COPY = {                  // errorType → visitor-facing copy
  REQUIRED_VALUE_ERROR:   (f) => `${f.label} is required.`,
  MIN_LENGTH_ERROR:       (f) => `${f.label} must be at least ${f.minLength} characters.`,
  MAX_LENGTH_ERROR:       (f) => `${f.label} must be at most ${f.maxLength} characters.`,
  FORMAT_ERROR:           (f) => FORMAT_COPY[f.format]?.(f) ?? `Please check ${f.label}.`,
  PATTERN_ERROR:          (f) => `${f.label} is not in the expected format.`,
  NOT_ALLOWED_VALUE_ERROR:(f) => `Choose one of the listed options for ${f.label}.`, // seed gap — see above
  TYPE_ERROR:             (f) => `Please check ${f.label}.`,
  UNKNOWN_VALUE_ERROR:    (f) => `Please check ${f.label}.`,   // usually a seed gap — see above
};

// Unrecognized errorType MUST degrade to safe copy — the enum grows, and MIN/MAX_VALUE_ERROR,
// MIN/MAX_ITEMS_ERROR and DISABLED_FORM_ERROR are all reachable without being mapped above.
function copyFor(field, fe) {
  const write = COPY[fe.errorType];
  if (write) return write(field);
  console.debug('unmapped form validation error', fe.errorPath, fe.errorType, fe.errorMessage);
  return field ? `Please check ${field.label}.` : 'Please check the highlighted fields.';
}

const fieldErrors = {};                                     // errorPath → visitor-facing copy
for (const v of (err?.details?.validationError?.fieldViolations ?? []))
  for (const fe of (v?.data?.errors ?? [])) {
    if (!fe.errorPath || fieldErrors[fe.errorPath]) continue;
    // Nested paths (`address/subdivision`, `attachments/0/fileId`) belong to the field named by the
    // FIRST segment; `fieldByTarget` is the projected `inputs` indexed by `target`.
    fieldErrors[fe.errorPath] = copyFor(fieldByTarget[fe.errorPath.split('/')[0]], fe);
  }

fieldErrors is then exactly what the render reads (fieldErrors[name]), keyed by the same string the inputs are named with.

UX — validate as they go, show the state on the field

Validate on blur, not only on submit. Making a visitor reach the submit button to learn that a field they left three inputs ago is wrong is a poor experience — catch it as they leave the field. Run fieldError on each control's blur; once a field has been flagged, re-run on input so the message clears the moment they fix it. Don't validate on the first keystroke of an untouched field — that flags a required field red before they've had a chance to type. Submit still runs the full pass as the backstop.

Show invalid state on the control, not only in the error text. A message under a tall form is easy to miss — give the control itself a visible affordance. Key it off the same aria-invalid attribute the validation already sets (per Accessibility below), so the visual and the assistive-tech state can't drift:

input[aria-invalid="true"], select[aria-invalid="true"], textarea[aria-invalid="true"],
fieldset[aria-invalid="true"] { border-color: #c0392b; outline-color: #c0392b; }

For a choice group the attribute is on the <fieldset>, so style that — and clear it the same way it was set: when fieldError returns empty, remove aria-invalid and the border goes with it. Don't track a separate .has-error class in parallel; one source of truth avoids a field that looks valid but reads invalid (or the reverse).

Accessibility (the inputs are generated — one slip lands on every field)

Because every control is generated from the schema, an accessibility mistake is systematic: it hits every field of every form. The render model already carries what's needed (target, label, required, options) — wire it up.

Associate each error with its control. Give the error a deterministic id from the same key as the errorPath (err-${target}, nested err-${target}/${sub}) and point the control at it with aria-describedby. The error element must:

• be role="alert" (or aria-live="polite") so a message appearing after submit is announced — aria-describedby alone only reads on focus;
• persist in the DOM, emptied/filled — conditionally rendering it ({err && …}) destroys the live region and nothing is announced; hide the empty state with CSS (.error:empty{display:none}), never by unmounting;
• carry aria-invalid only when invalid — pass undefined, not "false", so a clean field has no attribute.

const errorId = `err-${field.target}`;   // nested: `err-${target}/${sub}` — same key as errorPath
<input name={field.target} aria-describedby={errorId} aria-invalid={Boolean(err) || undefined} … />
<p className="error" id={errorId} role="alert">{err}</p>

A choice group's error attaches to the <fieldset>, not a radio. Radio (RADIO_GROUP) and multi-choice (inputType: "ARRAY") groups have no single control to describe — put aria-describedby (and aria-required for a required group) on the fieldset the render already emits; pointing it at one radio leaves the message unreachable from the other options.

⚠️ Marking a group invalid is a RadioNodeList trap. form.elements.namedItem(target) returns an HTMLElement for a text field or <select>, but a RadioNodeList for a radio/checkbox group — so a guard like if (control instanceof HTMLElement) silently skips every choice group (the visual .has-error styling still applies, so it's easy to miss). Handle both shapes:

const control = form.elements.namedItem(target);
const nodes = control instanceof RadioNodeList ? Array.from(control)
            : control instanceof HTMLElement ? [control] : [];
for (const node of nodes)
  message ? node.setAttribute('aria-invalid', 'true') : node.removeAttribute('aria-invalid');

On a blocked submit, focus the first invalid control — don't just scroll to it. scrollIntoView moves the viewport and nothing else; a keyboard/screen-reader user is left where they were. Focusing it lets role="alert" / aria-describedby announce what failed.

form.querySelector('[aria-invalid="true"]')?.focus();   // for a group, that's its first radio

Required needs more than the *. The bare * the render adds is read as "star" or skipped — keep it but hide it from AT (aria-hidden="true") and let the control's required attribute (or aria-required on a group) carry the meaning. Do both; never the glyph alone.

Every control needs a real name. The projection falls back to label ?? target, so a seed that omits a label announces as person_name — render a real <label>; a placeholder is not a label (it disappears on input and fails contrast).

Announce success too. Swapping the form for a thank-you block is a silent DOM change — give the success region role="status" (or move focus to its heading with tabindex="-1"), or the user is left on a button that appears to have done nothing.

Don't reach for role="form", an aria-label on a native input that already has a <label>, or a custom role="radio" — native radios inside a <fieldset> are already a correct radiogroup with arrow-key selection.

Spam protection (only if the site raised it)

The seed leaves spamFilterProtectionLevel at its default (ADVANCED), and an anonymous visitor submit still succeeds without a captcha token on the headless SDK path. So you normally pass no options. Only if a site is configured to require a CAPTCHA do you need to solve one and pass it as the second arg: createSubmission(submission, { captchaToken }). Don't add captcha plumbing speculatively — the default path needs none.

Conclusion

A correct Wix Forms frontend:

• reads the live schema with the forms export of @wix/forms (getForm/listForms/queryForms) on the plain visitor token — NO auth.elevate: the schema read is visitor-accessible on every framework incl. a pure SPA, despite the docs marking it owner-scoped;
• renders schema-driven — projects form.formFields into a render model and generates one input per field, ordered by steps[], so a dashboard field add/remove/relabel or a tightened constraint reflects with no code change. Derives both options-block names from the inputType / componentType enums rather than hardcoding a fallback chain, carries the owner's default prefill, and skips the input types it has no control for (BOOLEAN, WIX_FILE, PAYMENT, SCHEDULING) instead of letting them fall through to a text input;
• validates schema-driven on the client and treats the server as authoritative: pre-checks required + minLength/maxLength/pattern + format keyed off field.format, never the field name, with each client rule at least as strict as the server's and the normalized value (e.g. E.164 phone) submitted — never the raw one; always maps createSubmission's fieldViolations[].data.errors[].errorPath back to per-input errors as the backstop, writes every visitor-facing message from errorType plus the field's projected schema (never parsing or displaying the validator's errorMessage), and defaults an unrecognized errorType to safe copy;
• shows any user-visible example — a phone number above all — for the field's own country (allowedCountryCodes / defaultCountryCode, else the site's), always from that country's regulator-reserved fictional range, and never submits it;
• imports the submissions export of @wix/forms and calls submissions.createSubmission(submission, options) — positional args, the submission object first (never { submission }-wrapped) — binding each input's name = the schema's target so the submissions map is keyed by target by construction;
• submits on the plain visitor token with NO auth.elevate (anonymous submit works; a pure SPA can't elevate anyway) and, at the default ADVANCED protection, no captcha;
• only writes submissions — reading them back is owner-only — and shows the thank-you for CONFIRMED, PENDING or PAYMENT_WAITING (all three are created submissions; a payment form surfaces the payment step within that success state, never as a failed submit); reads the created id as result._id, never result.id;
• is accessible by construction (the inputs are generated, so a slip repeats on every field): each error carries a deterministic id from its errorPath and is referenced by aria-describedby
  • role="alert" and persisted (not conditionally unmounted); a choice group's error and aria-invalid attach to the <fieldset> (mind the RadioNodeList from form.elements.namedItem); a blocked submit focuses the first invalid control; required is programmatic, not just *; and the success state is announced (role="status");
• treats an UNKNOWN_VALUE_ERROR on a correctly-spelled target, or a NOT_ALLOWED_VALUE_ERROR on a choice field, as a seed gap to fix in setup-forms.md — not a frontend bug.