About Form Fields

A form schema's formFields array defines every element a form displays, from text inputs to payment fields to the submit button. This article explains how to compose a field correctly, which values to use for each kind of field, and which fields depend on a premium plan or another Wix app.

The Form object reference documents each field property individually. This article covers the parts that the property descriptions can't convey on their own: how the properties combine, and which combinations produce which field.

How a field is composed

Every field sets fieldType to either INPUT or DISPLAY:

• INPUT fields collect data from submitters, and put their configuration in inputOptions.
• DISPLAY fields show information without collecting data, and put their configuration in displayOptions. Rich content and the submit button are display fields. See Display fields.

An input field is defined by 3 values that must agree with each other:

• inputOptions.inputType sets the data type the field collects, such as STRING or ARRAY.
• inputOptions.<inputType>Options.componentType sets the UI component that renders the field, such as TEXT_INPUT or DROPDOWN.
• inputOptions.<inputType>Options.<componentType>Options holds the component's settings, such as its label and choices.

Both nested object names follow the same rule: take the enum value, convert it to camelCase, and append Options. For example, inputType: STRING nests under stringOptions, and componentType: TEXT_INPUT nests under textInputOptions:

Because this rule is consistent, you can construct any field object from the table in Field types plus the component's property list in the reference. The Create Form method includes complete request examples for common form types, such as a contact form, a feedback survey, and an order form.

Field identifiers

identifier labels a field with its purpose. Unlike target, which names the key a submitted value is stored under, identifier tells Wix apps what kind of field they're looking at.

Use the known values listed in Field types. Wix Forms uses identifier to render submissions in the submission table, so a field with a missing or non-standard identifier may display incorrectly there, even though the form itself works and the API accepts the request.

Identifiers starting with CONTACTS_ mark fields that map to a contact property. These fields also set inputOptions.contactMapping, which makes form submissions create or update a contact. See Contact fields.

The identifiers in this article are the ones used by the Wix Forms namespace, wix.form_app.form. Apps made by Wix that own their own namespace may define additional identifiers for the same components, so a form schema in another namespace can carry identifiers not listed here.

Field types

The following table lists every supported field and the values that produce it. Unless noted, fieldType is INPUT.

Display fields

Rich content and the submit button are display fields. They set fieldType to DISPLAY and have no input type or component type. Instead, displayOptions.displayFieldType selects the element, and its settings nest under the matching options object.

A rich content field shows formatted text, images, or links without collecting a value. Its content is a Ricos rich content object, and maxShownParagraphs optionally collapses longer content behind an expandable section:

The submit button renders the form's navigation and submit controls:

Some component types serve several fields

A component type doesn't always match its field's identifier, because several fields share a general-purpose component. When you read an existing form schema, componentType alone doesn't tell you which field a developer intended. Check identifier instead:

• TEXT_INPUT: Short answer, Long answer, Link, Email, Address, First name, Last name, Company, Position, Tax ID.
• DATE_INPUT: Date, Birthdate.
• CHECKBOX: Checkbox, Subscribe checkbox.
• CHECKBOX_GROUP: Multi choice, Image choice, Product.

This has practical consequences:

• A long answer field sets componentType to TEXT_INPUT, not to a separate text area component. Only identifier: TEXT_AREA distinguishes it from a short answer.
• An image choice field sets componentType to CHECKBOX_GROUP. Only identifier: IMAGE_CHOICE distinguishes it from a multi choice field.

Validation

The validation object

Always include validation, even when it's empty: {}. It goes inside the field's input type options object: stringOptions.validation for a STRING field, arrayOptions.validation for an ARRAY field, and so on. The appointment field is the only exception, since its schedulingOptions has no validation object.

Nest it under the object named after the field's inputType, not its componentType. Placing it under the wrong object is accepted at creation, but leaves the field with no validation the form recognizes.

Format constraints

Several fields rely on validation.format rather than a distinct component to constrain what submitters can enter. Set it inside the input type's options object:

• Link: URL
• Email: EMAIL
• Phone: PHONE
• Birthdate, Date, Date picker: DATE
• Date and time: DATE_TIME
• Time: TIME

To leave a string field's format unconstrained, either omit format or set it to UNKNOWN_FORMAT.

A link field, for example, is a text input that validates its value as a URL:

Phone fields accept an optional validation.phoneOptions.allowedCountryCodes array of ISO 3166-1 alpha-2 codes, which limits the countries a submitter can select. Omit it to allow all countries. To preselect a country, set phoneInputOptions.defaultCountryCode.

What each field submits

A field's inputType determines the shape of the value it collects, so it also determines what a submission carries for that field. A STRING field submits a string, an ARRAY field an array, and an ADDRESS field an object. This is why the single-line address field and the multi-line address field aren't interchangeable even though both map to the contact's address.

For the full mapping, see About Submission Values in the Form Submissions API.

Choice fields

Single choice, multi choice, image choice, dropdown, and tag picker fields each declare their choices twice, and the 2 declarations must agree:

• The component's options array defines what submitters see. Each option needs an id, a label, and a value.
• The field's validation declares the accepted values. If these don't match the option values, submissions fail validation.

Where validation lives depends on the input type. STRING fields declare validation.enum, while ARRAY fields declare validation.items.stringOptions.enum:

Give every option a lowercase GUID id. An option without one is rejected at creation.

For ARRAY fields, validation.items needs both itemType and the matching options object, as in the multi choice example above. Passing one without the other, or leaving items empty, either fails at creation or produces a field the form can't validate submissions against.

Use numberOfColumns to lay choices out. Image choice fields typically use TWO or more, and tag pickers use ZERO to flow tags inline.

Service picker fields follow the same pattern, but each option value is a Wix Services service ID rather than free text.

Checkbox labels use rich content

Checkbox and subscribe checkbox fields take a Ricos rich content object as their label, not a plain string. This lets a label contain links, which consent text often needs:

Every other field type takes a plain string label.

Contact fields

Fields with a CONTACTS_ identifier write their value to a contact property. Set inputOptions.contactMapping.contactField to the target property, and mark the field pii: true so Wix encrypts the stored value.

contactField accepts FIRST_NAME, LAST_NAME, COMPANY, POSITION, EMAIL, PHONE, ADDRESS, BIRTHDATE, VAT_ID, CUSTOM_FIELD, and SUBSCRIPTION. A tax ID field uses the CONTACTS_TAX_ID identifier and maps to the VAT_ID contact field.

Some contact fields need extra mapping detail:

• EMAIL: emailInfo.tag
• PHONE: phoneInfo.tag
• ADDRESS: addressInfo.tag
• SUBSCRIPTION: subscriptionInfo.subscriptionChannels
• CUSTOM_FIELD: customFieldInfo

The remaining contact fields need only contactField.

A subscribe checkbox uses the SUBSCRIPTION contact field to opt submitters into a channel:

Both the address field and the multi-line address field map to the ADDRESS contact property. They differ in structure: the address field is a single text input, while the multi-line address field collects each part of the address separately.

For a multi-line address, validation.fields sets which subfields are required. It accepts country, addressLine, addressLine2, city, postalCode, subdivision, streetName, and streetNumber.

Visibility is controlled separately and covers 1 subfield: multilineAddressOptions.fieldSettings.addressLine2.show shows or hides the second address line. The other subfields don't have a visibility setting.

A multi-line address is submitted as an object rather than a string, with country as an ISO 3166-1 alpha-2 code. Both country and subdivision are validated against the values allowed for the selected country, so a free-text subdivision is rejected. Mark subdivision as required only when the form presents the valid options for the chosen country.

Setting contactMapping is all that's needed. When someone submits the form, Wix creates or updates the contact from the mapped fields, with no further configuration on the form.

Payment fields

All 4 payment fields set inputType: PAYMENT and declare what's for sale in paymentOptions.validation.products. Each product sets a priceType:

• FIXED_PRICE products set an amount in fixedPriceOptions.price.
• DYNAMIC_PRICE products let the submitter enter an amount, with an optional floor in dynamicPriceOptions.minPrice.

The component determines how those products are presented:

For product and donation fields, the component's options array references products by ID. Each option's value must be the id of a product declared in validation.products:

Appointment fields

An appointment field lets submitters book a slot. It sets inputType: SCHEDULING and configures the appointment itself, rather than referencing an existing service:

• name and durationInMinutes define the appointment.
• staffIds lists the staff members who can take it.
• format sets how the appointment takes place, such as PHONE, with matching options in phoneOptions.
• manualApprovalRequired controls whether a booking needs confirmation.

This differs from the service picker fields, which reference services already defined in Wix Services.

Field order comes from the layout

formFields is an unordered set. The order fields appear in that array isn't the order they're displayed in, and the submit button can appear anywhere in it. To render a form in the right order, read steps.

Each step is a page. Its layout holds a breakpoint object for large, medium, and small screens, and each breakpoint's items positions a field by row and column, matching the field through fieldId. Sort a breakpoint's items by row, then by column, and resolve each fieldId against formFields to get the display order.

A breakpoint is only present when the form defines a layout for it, so fall back to another breakpoint rather than assuming large exists.

Every field must appear in the layout, including the submit button. A field that isn't placed still stores submitted values, but the Wix dashboard renders it, and the submissions made against it, as empty.

The server stores id in lowercase, so pass a lowercase GUID for id and match it with a lowercase fieldId in the layout. An uppercase id still saves, but the layout's fieldId no longer matches it once the form schema is stored, so the field is silently unplaced.

Field requirements

Premium plan

File upload, signature, and all 4 payment fields are premium features. The site needs a Core premium plan or higher. Creating a form schema that includes one of these fields on a site without a qualifying plan fails.

The site's plan also caps how many fields a single form schema can hold, and how many form schemas the site can have. Creating a form schema that exceeds either cap fails rather than truncating. Both caps depend on the plan, so read the current values with List Forms Providers Configs instead of assuming a fixed number. Splitting a single logical form across several schemas to stay under the field cap trades a single submission record for several, and consumes more of the site's form allowance.

Another Wix app

Some fields depend on another Wix app for the site:

• Product, Fixed price, Custom price, Donation: Wix eCommerce
• Appointment: Wix Meetings
• Service picker, Multi-service picker: Wix Services

Creating a form schema that includes one of these fields on a site without the required app fails.

Payment fields also require a premium plan, in addition to Wix eCommerce.

File upload and signature fields

File upload and signature fields both use inputType: WIX_FILE, and both constrain uploads through validation:

• uploadFileFormats limits accepted file types, such as IMAGE or VIDEO.
• fileLimit sets how many files a submitter can upload.

A signature field stores the drawn signature as an image, so it sets uploadFileFormats to ["IMAGE"] and fileLimit to 1.

See also

• Form object
• Create Form
• About the Form Schemas API