/wix-vibe-headless

Wix Forms — client utils (you build the UI)

Intent: contact / enquiry / lead / signup / waitlist / application / feedback / survey / quote request / intake or registration — any form a visitor fills in and submits. Whether the submission also becomes a CRM contact is a per-field mapping, not a different vertical.

This vertical ships no UI: the owner picks the fields in their dashboard, so every form has a different field set and no "contact form" component could ship for it. You write one control per field — the shipped utils supply the schema behind it, the state, the validation and the submit. Everything runs on the public WIX_CLIENT_ID (anonymous visitor token) — no SDK, no backend, no elevated credential.

⚠️ A visitor-fillable form is FORMS, not CMS. Wiring one to insertDataItem works, and is the wrong call: it gives up the dashboard form builder, spam protection, notifications and contact mapping, and needs the owner to set collection permissions before a visitor can submit at all. Use cms only when the app must read the entries back (a gallery, a listing, "my submissions") — a visitor cannot read Forms submissions. Submit-only → forms.

⚠️ "Add a field" is a SCHEMA change. "Add a dropdown for job industry", "make the phone optional", "drop the budget question" — all reads like UI work and all are a PATCH to the live schema (seed/SEED.md, REVISE): patch it, verify, rewrite wix-forms.config.js, then wire the control. A field the visitor can fill that isn't in the schema is silent data loss — the value reaches no submission, inbox or contact, and the submit still resolves true.

What ships (utils only)

Prerequisites — a HARD GATE

• src/rest/wix-forms.config.js must exist. No file → the seed hasn't succeeded → stop and run the seed. It's the one vertical whose client can't be built in parallel with its seed.
• Never invent a formId, and never write that file early. Its only value is as proof that a verified schema exists; the seed writes it after creating and verifying each schema.
• The Wix Forms app installed, with at least one form. This vertical doesn't provision forms.
• No permission setup — unlike CMS, a visitor can read a published form's schema and submit to it out of the box.

Build the UI

The schema is the source of truth, whatever the markup looks like. Every target, label, required flag, constraint and choice option comes from it, and so does the submission map — nothing about a field is yours to invent.

The markup is yours to author. Write a JSX element per field (step 5) when the layout matters, which on a designed page it usually does. Loop over read.orderedInputs(form) with a branch per control type instead when the owner will keep editing the form, and a dashboard change should reach the site with no code touch. The per-field wiring is identical either way.

The JSDoc in hooks/useWixForm.js and lib/wix-form-schema-utils.js covers what each util does; this covers which control a field wants and where the obvious implementation is wrong. Markup and styling are yours (on base44: shadcn + src/index.css).

1 · Load the form

import { useWixForm, FORM_ERROR } from "@/hooks/useWixForm";
import { WIX_FORMS } from "@/rest/wix-forms.config";   // written by the seed — never by hand

const { form, values, setValues, submit, validate, errors, loading, read } =
  useWixForm(WIX_FORMS.contact.formId);

const fields = read.orderedInputs(form);   // what the form contains, in the owner's layout order

Fields are the raw objects Wix sent, so anything the accessors don't cover is still on them — pii, showLabel, buttonText, explanationText, options[].image, the steps[] a multi-page form would need.

contact is this example's key. The seed names each form — waitlist, quote, application — so use the keys wix-forms.config.js actually contains.

Several forms on one page? The hook loads one schema each. Past two, call listForms({ formIds: [...] }) once (up to 100 ids) and run orderedInputs over each result.

Set the site's country once at app start, so locale-derived examples match the business, not the visitor's browser:

import { setSiteCountry } from "@/rest/wix-forms";
setSiteCountry("GB");

2 · Render one control per field

Author them or loop over them — every control carries the same four things, and bind(target) from the hook supplies the first three:

1. name = the field's target — the immutable storage key, and also the state key, the error key and the submission key. Keying everything by it makes the submission right by construction; it's how a blocked submit finds the control to focus, and it drives autofill.
2. value from values[target], written back through setValues. (A choice group carries checked instead; a file input can't be controlled at all and takes only onChange.)
3. onBlur → validate(target) — not on the first keystroke of an untouched field, which reddens a required field before the visitor types. Once flagged, re-check as they type from an effect on the value: React hasn't committed the new value when onChange runs, so a check there judges the value they just replaced.
4. A real <label>, and an error node — see step 6 for the wiring both need. bind sets the error node's aria-describedby/id pair (err-${target}); you render the node itself.

Stamp the schema's constraints as native attributes. They reinforce the JS checks and drive mobile keyboards:

A constrained field with no placeholder gets a synthesized one: PHONE → phoneExample(read.phoneCountryOf(field)) (that country's regulator-reserved fictional number, falling back to the site's), URL → https://…. It prevents the must match format "phone" rejection without a hint line under every field.

Which control

identifier and componentType are independent axes — several fields share one component — so branch on whichever distinguishes the control, and never on the target name, which an owner's rename silently breaks.

Two that bite: componentType is TEXT_INPUT for short and long answer, so keying a textarea off it renders every long field single-line; and IMAGE_CHOICE is indistinguishable from multi choice except by identifier — it falls out as plain checkboxes, and its pictures are on componentOf(field).options[].image.

Coverage check — every field kind an owner can add:

orderedInputs returns the uncovered types too — nothing is filtered for you. Write the control, or have the owner drop the field; a required field you don't render makes the form unsubmittable.

Display fields never reach this loop. RICH_TEXT blocks and the submit button are fieldType: "DISPLAY", so orderedInputs drops them. If a form uses rich-content blocks as section copy between fields, read them off form.formFields yourself — their content is Ricos, not a string.

Wix's About Form Fields is the spec behind this table. seed/SEED.md carries the same identifiers from the authoring side (which JSON creates each field); this one is the rendering side (which control, which value shape) — they join on identifier.

Controls that need more than an input

Choice groups go in a <fieldset> with a <legend>; the group's aria-describedby, aria-invalid and aria-required go on the fieldset, since no single radio can carry them. Options come from read.choicesOf(field) ({ value, label }, label falling back to value). A checkbox group's value is an array — toggle values in and out of it.

A dropdown needs a disabled <option value=""> first (state starts empty, so otherwise the first real option looks pre-selected); use componentOf(field).placeholder for its text.

An address is a group whose value is a nested object. Subfields come from read.addressPartsOf(field) ({ sub, required }, hidden addressLine2 already dropped); name each control ${target}/${sub}, which is exactly the server's error path for a nested field, so rejections land on the right control with no mapping of your own. Subfield keys are storage keys — humanize them (postalCode → "Postal code"). country and subdivision are country-dependent enums the schema doesn't enumerate: render country as a select over ISO-3166 alpha-2 codes, narrowed to validationOf(field).allowedCountries when set. Keeping subdivision free text means leaving it optional and relying on the mapped error.

File uploads — the value is the upload URL

The hook's submit runs this before it sends anything:

1. getMediaUploadUrl(formId, filename, mimeType) → a signed uploadUrl. This Forms-scoped wrapper is what makes a visitor upload possible at all: site-media directly needs a Manage-Media credential and 403s for a visitor.
2. PUT the bytes to it with the file's Content-Type, via plain fetch — the URL is pre-signed, and adding the visitor's Authorization header turns a working upload into a 400.
3. Submit that same uploadUrl as the value — not the CDN URL the upload returns, not a file id. One file submits the string; several submit an array.

So values[target] holds File objects until submit, and validation checks the count (required, fileLimit) since no string rule applies. Three render consequences: the input can't be controlled (wire onChange, list the picked filenames yourself); clearing it after success needs a key you bump in handleSubmit, because resetting state leaves the browser's own "1 file selected" text; and uploads run inside loading, so the button's progress state matters more here.

A signature shares WIX_FILE, so a file input accepts one — but the honest control is a canvas: canvas.toBlob(...) → a File named signature.png in values[target], same upload path.

Never base64 a file into a value. It stores no real file and blows past the submission size limit. A form with no file field at all is a plan gate — file, signature and payment fields need a Core-or-above plan — fixed by the owner's plan, never an inlined blob.

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

validate(target?) applies only rules the schema states:

Call it as validate("email") (the onBlur wiring), validate("address/city") for one subfield, or validate() for everything — submit already does the last, so reach for it only to gate something else. It reads values, and it clears what now passes as well as flagging what doesn't. An address subfield gets the required check only; country/subdivision content is the server's call.

Show invalid state on the control, keyed off the same aria-invalid the render sets, so visual and assistive-tech state can't drift — no parallel .has-error class:

input[aria-invalid="true"], select[aria-invalid="true"], textarea[aria-invalid="true"],
fieldset[aria-invalid="true"] { border-color: var(--destructive); outline-color: var(--destructive); }
.error:empty { display: none; }

Never key a check on a field's name (the classic slip: keying the email check on target === "email") — derive it from format and the schema's constraints, as validateField does. And a client rule laxer than the server's is worse than none: the visitor then learns about the problem after a round trip, in Wix's wording instead of yours.

4 · Submit

submit(event) client-validates → uploads picked files → builds the submission map (empty optionals dropped, PHONE normalized to E.164, NUMBER coerced; it walks the schema, so a stray key in values can't reach the API) → creates the submission → maps server violations onto controls and focuses the first invalid one. On success it resets values to the schema's defaults.

The resolved true is the only success signal there is. Submissions are write-only from the browser — reading them back needs an owner scope and 403s for a visitor. The submission lands in the owner's dashboard.

CONFIRMED, PENDING and PAYMENT_WAITING all mean created. A PAYMENT_WAITING form leaves the visitor a payment step: surface it inside the success state, never as a failed submit.

No captcha at the default protection level — don't add captcha plumbing speculatively.

5 · The whole component

Author one JSX element per field, using the targets the seed wrote and the constraints the schema states. bind(target) supplies the wiring every control shares — name, value, onChange, onBlur, aria-describedby, aria-invalid — so a field is a label, a control and its error node:

export default function ContactForm() {
  const { form, values, bind, setValues, submit, validate, errors, loading, read } =
    useWixForm(WIX_FORMS.contact.formId);
  const [sent, setSent] = useState(false);

  async function handleSubmit(event) {
    setSent(await submit(event));   // true only when the submission was created
  }

  if (loading && !form) return <p>Loading…</p>;
  // A form that can't load is a setup problem — say so; never fall through to a hand-built form,
  // which silently drops real enquiries.
  if (!form) return <p role="alert">This form isn't available right now. {errors[FORM_ERROR]}</p>;
  // Swapping the form out is a silent DOM change, so the success state announces itself.
  if (sent) {
    return (
      <div role="status">
        <h3 tabIndex={-1}>Thank you</h3>
        <p>We'll be in touch shortly.</p>
        <button type="button" onClick={() => setSent(false)}>Send another</button>
      </div>
    );
  }

  return (
    <form onSubmit={handleSubmit} noValidate>
      <label>
        <span>Your email<span aria-hidden="true"> *</span></span>
        <input {...bind("email_a1b2")} type="email" required autoComplete="email" />
        <p className="error" id="err-email_a1b2" role="alert">{errors.email_a1b2}</p>
      </label>

      <label>
        <span>How can we help?</span>
        <textarea {...bind("message_c3d4")} rows={5} maxLength={500} />
        <p className="error" id="err-message_c3d4" role="alert">{errors.message_c3d4}</p>
      </label>

      {/* A choice group carries `checked` rather than `value`, so wire it by hand — same name,
          same onBlur, and the aria-* on the fieldset because no single radio can hold them. */}
      <fieldset aria-describedby="err-budget_e5f6" aria-invalid={Boolean(errors.budget_e5f6) || undefined}>
        <legend>Budget</legend>
        {["Under £5k", "£5k–£20k", "Over £20k"].map((option) => (
          <label key={option}>
            <input type="radio" name="budget_e5f6" value={option}
                   checked={values.budget_e5f6 === option}
                   onChange={() => setValues((v) => ({ ...v, budget_e5f6: option }))}
                   onBlur={() => validate("budget_e5f6")} />
            {option}
          </label>
        ))}
        <p className="error" id="err-budget_e5f6" role="alert">{errors.budget_e5f6}</p>
      </fieldset>

      <p role="alert">{errors[FORM_ERROR]}</p>
      <button type="submit" disabled={loading}>
        {loading ? "Sending…" : (read.submitTextOf(form) || "Submit")}
      </button>
    </form>
  );
}

The targets (email_a1b2, …) come from WIX_FORMS.<key>.targets — never invent or shorten one, since a key that isn't an exact schema target 400s the whole submission. Everything else on each control comes from that field's schema entry (step 2): its label, its required, its length/pattern bounds, its choice options. noValidate keeps your messages instead of the browser's bubbles; the native constraints still drive keyboards and assistive tech.

Authoring beats looping here, because the layout is the point: a two-column name row, a budget group styled as cards, copy between sections. Loop instead when the owner will keep editing the form — read.orderedInputs(form).map(...) with a branch per control type keeps a dashboard change reaching the site with no code touch. Either way the wiring per field is what's above.

Two things the shell doesn't show:

• Server violations land on controls, keyed exactly like the client's (target, or target/sub for an address subfield). The copy comes from the violation's errorType plus the field's schema; an unmapped type degrades to safe copy, and Wix's internal errorMessage goes to console.debug. Only a failure with no per-field violations sets errors[FORM_ERROR].
• A required field you didn't render blocks submit with a message that has no control to display it. Check read.orderedInputs(form) against your branches before shipping.

6 · Accessibility — the controls are generated, so one slip hits every field

• The error node renders always, empty or filled, with role="alert" and a deterministic id (err-${target}) the control points at via aria-describedby. aria-describedby alone only reads on focus; conditional rendering ({error && …}) destroys the live region entirely. Hide the empty state with CSS.
• aria-invalid only when invalid — undefined, never "false".
• A group's error and aria-* go on the <fieldset> — choice groups and addresses have no single control to describe.
• Required is programmatic: the required attribute (or aria-required on a group) carries the meaning, the * is aria-hidden decoration. Both, never the glyph alone.
• Every control has a real <label> — a placeholder disappears on input and fails contrast.
• The success state is announced (role="status", or focus its heading).

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

Hard rules

• A visitor-fillable form is this vertical, not cms.
• Never hold a form field in local component state — a value outside the hook's values submits nothing. Adding a field is a schema change: seed/SEED.md, REVISE.
• Never answer a field request with a dashboard link — that link is for the owner's own edits.
• Read and write only through the shipped helpers — never hand-build a Wix Forms URL.
• Never invent a target, label, option or constraint — every one comes from the schema (authored markup included). Never detect a control by its target name either.
• Read fields through the accessors, not by reaching into inputOptions — the block names are enum derived, and the accessors map every one of them.
• Key every control by target: values[target], errors[target], name. Address subfields use target/sub.
• Derive validation from the schema, and keep every client rule at least as strict as the server's.
• Never add auth.elevate, a backend function or a connector token to make a form work. The visitor token reads the schema and creates the submission; the API spec's owner scopes are wrong for the published-site path. This is the most common wrong turn on this vertical.
• Submissions are write-only from the browser — the resolved createSubmission is the success signal. Listing entries back needs cms.
• Every status the submit resolves on is a created submission: show the thank-you, and put a payment step inside it. Treating one as failure costs the owner duplicates.
• Order comes from steps[], not formFields[]; take the order only, not the geometry.
• Render every field orderedInputs returns, or confirm what you skip isn't required.
• A file field submits the URL from getMediaUploadUrl — never base64, never a Manage-Media credential, never the CDN URL the upload returns.
• UNKNOWN_VALUE_ERROR / NOT_ALLOWED_VALUE_ERROR are seed bugs — fix the schema, don't mangle the key or value.
• Never mock a form. No formId, or a form that won't load, is a setup problem to surface.
• Never show a locale-wrong example, and never submit the reserved one you display.

Fallback

Three sources answer what this file doesn't: the JSDoc in hooks/useWixForm.js and lib/wix-form-schema-utils.js; the Wix reference below; and seed/SEED.md for how a field was authored, and REVISE for changing one. Calling an endpoint the helpers don't wrap is fine via wixApiRequest — first look up the exact method and body in official Wix API documentation using the documentation skill available in your environment; never guess.

• Form object (the shape form and its fields arrive in): https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object.md
• Form Schemas API: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas.md
• About Form Fields (every field-level rule): https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md
• Form Submissions API: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions.md
• About Submission Values (per-inputType value shapes): https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md
• Validation errors: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction#validation-errors
• Get Media Upload URL: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/get-media-upload-url.md
• Uploading to a generated URL: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/upload-api.md

Not this vertical

An event RSVP → events (it ships its own registration form). A bookable service's form → bookings. Content the app lists back — reviews, galleries, "my items" → cms. A form only logged-in members may reach → members for the gate, forms for the form. SKILL.md's routing table is the deciding copy.

Seeding

Seed per seed/SEED.md: it installs the Forms app, creates each schema, verifies it (reads it back, checks the dashboard summary, sends and deletes one real submission), then writes src/rest/wix-forms.config.js. Needs an elevated credential, and does not run in parallel with the client — see Prerequisites.

Changing a form that already exists — a new field, a relabel, a tightened rule — is that doc's REVISE action: PATCH on the current revision, re-verify, rewrite the config, wire the control. Never a second create.

Point the user to their dashboard

Substitute the site's metaSiteId:

• Forms list — https://manage.wix.com/dashboard/{metaSiteId}/wix-forms
• Form builder — https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId} → where the owner edits fields; a relabel or new option reaches a looped form with no code change, a new field still needs a control. Asked to change the form yourself? REVISE, not this link.
• Submissions — https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}/submissions → per form, off its builder path; there's no site-wide submissions page to link
• Contacts — https://manage.wix.com/dashboard/{metaSiteId}/contacts → contact-mapped fields create or update a contact automatically.

Verify

• wix-forms.config.js exists; every formId comes from WIX_FORMS, none typed by hand.
• Every control's name inside the <form> is a target in WIX_FORMS.<key>.targets, and its value lives in the hook's values — no field is backed by local state.
• WIX_CLIENT_ID set (not the placeholder).
• Looped form: relabel a field in the dashboard, reload, the new label appears with no code change. Authored form: every target in the JSX matches WIX_FORMS.<key>.targets exactly.
• Every field read.orderedInputs(form) returns has a control — long answer is a <textarea>, choice groups render their options, an address renders its subfields — or what you skipped isn't required.
• Required fields show inline errors on blur, in your wording, before any round trip.
• A deliberately invalid email/phone is rejected inline, on the right control.
• A real submission shows the thank-you, then appears in the owner's submissions inbox and (for contact-mapped fields) as a contact.
• Has a file field? Attached a real file, submitted, and opened the attachment from the dashboard — a submission recording an unusable attachment still "succeeds".
• Keyboard pass: a blocked submit focuses the first invalid control, errors are announced, every control has a real label.
• No auth.elevate, backend function or connector token in the submit path.