Form Fields

The native forms validate what shoppers type: maximum lengths and regular expressions for the address fields, the contact phone, and the cardholder name. A version can override those rules with the formFieldsController prop, without touching any component. Typical reasons: a carrier that rejects long street names, a platform that only accepts digits in the house number, or a market where the default character rules are too strict.

Where to edit

Admin → Versions → your version → Props Configuration → Custom props. Click Add Form config in the empty state, or + Add Prop and pick Form config from the list, then edit the JSON and click Save Changes.

Version Props Configuration tab — The Custom props block with its presets

The preset the Admin inserts is an example, not the built-in defaults. Review every field it lists before saving, and delete the ones you do not want to change.

Shape

{
  address?: {
    number?:       FieldControl;
    neighborhood?: FieldControl;
    street?:       FieldControl;
    complement?:   FieldControl;
    reference?:    FieldControl;
    name?:         FieldControl;   // applies to first name and last name
    city?:         FieldControl;
    phone?:        FieldControl;   // applies to phone and company phone, checked against the digits only
  };
  profile?: {
    phone?:        FieldControl;   // the contact-details modal; independent of address.phone
  };
  creditCard?: {
    name?: { maxLength?: number; regex?: string };   // a single pattern as a string
  };
}

type FieldControl = {
  maxLength?: number;
  regex?: Array<{ id: string; pattern: string }>;
};

How the rules apply:

A field you leave out keeps the built-in rules.
For a field you include, your regex list replaces the built-in patterns for that field, and maxLength replaces the built-in limit. Include every pattern you still want.
Patterns are tested with the Unicode flag, so \p{L} works.
When a pattern fails, the shopper sees the message with key addressForm_<id>. Two ids ship with messages in every locale: specialCharsValidationMessage and lettersOnlyValidationMessage. For a new id, add the addressForm_<id> message in the Messages tab.

Example

Allow only digits in the house number, keep the standard character rule on the street with a shorter limit, forbid digits in names, limit the contact phone, and shorten the cardholder name:

formFieldsController

{
  "address": {
    "number": {
      "maxLength": 10,
      "regex": [{ "id": "digitsOnlyValidationMessage", "pattern": "^[0-9]+$" }]
    },
    "street": {
      "maxLength": 200,
      "regex": [{ "id": "specialCharsValidationMessage", "pattern": "^(?![\\d.]+$)[\\p{L}0-9\\s\\-.,#&'’()/]*$" }]
    },
    "name": {
      "regex": [{ "id": "lettersOnlyValidationMessage", "pattern": "^[^0-9]*$" }]
    }
  },
  "profile": {
    "phone": { "maxLength": 11 }
  },
  "creditCard": {
    "name": { "maxLength": 60, "regex": "^[^0-9]{1,60}$" }
  }
}

The digitsOnlyValidationMessage id above is new, so pair it with a message in the ui row of the Messages tab:

{
  "addressForm_digitsOnlyValidationMessage": "Use digits only"
}

Remember to escape backslashes in JSON: \d is written \\d.

Translations: the messages the validation ids point to
Checkout Flags: the other settings on the Props tab
Managing Versions: how the Props tab saves

Overview

Start Here

AI Coding Agents

Core Concepts

Customization

Ollie Studio

Functions

CLI Reference

Ollie SDK

Analytics & Scripts

Tools & Tips

Product updates

Where to edit

Shape

Example

​Where to edit

​Shape

​Example

​Related

Where to edit

Shape

Example

Related