Customize the address fields validation of Checkout

Customize the validation rules for the address fields in your checkout experience.

Checkout lets you customize the frontend validation rules for the shipping and billing address fields of your checkout experience.

You can customize the validation rules according to your needs to obtain accurate address data. This way, you can reduce errors related to address entry by your customers.

If the billing and shipping address forms contain the same field, the customization applies to both forms. For example, if you customize the validation rules of the firstName field, the rules will apply for the field on both the billing and shipping address forms.

Address fields validation is a frontend validation only.

Default values

Following are the default validation rules for the address fields. For information on the customization of the validation rules, see the following customization examples.

Default validation rules for address fields

Field	Required	Pattern	Length
`firstName`	Yes	-	-
`lastName`	Yes	-	-
`email`	Yes	`/^\S+@\S+\.\S+$/`	-
`country`	Yes	-	-
`streetName`	Yes	-	-
`streetNumber`	No	-	-
`additionalStreetInfo`	No	-	-
`postalCode`	Yes	See Default postal code validations patterns.	-
`state`	Yes	-	-
`city`	Yes	-	-
`phone`	No	`/^[0-9()+\-\s]+$/`	`maxLength`: 15 characters
`company`	No	-	-

For information on field label customization, see Texts and labels.

Default postal code validation patterns

Country	Country code	Pattern
France	`FR`	`/^\d{2}[ ]?\d{3}$/`
Germany	`DE`	`/^[\d]{5}$/`
Italy	`IT`	`/^[\d]{5}$/`
Netherlands	`NL`	`/^\d{4}\s{0,1}[A-Za-z]{2}$/`

Default error messages

Error	Displayed message
A required field was not filled in.	Required field
The postal code entered does not meet the default validation pattern.	Invalid ZIP Code
The email address entered does not meet the default validation pattern.	Invalid email address
The phone number entered does not meet the default validation pattern.	Invalid phone number

For information on message customization, see Texts and labels.

Customization examples

To customize the frontend validation rules for the address fields, you must pass the forms object with the checkoutFlow method when initializing Checkout. Following are some customization examples.

Deactivate default validation rules for all fields

You can deactivate the default validation rules for all address fields by setting disableDefaultValidations to true.

Deactivate the default validation rules for the address fieldsJavaScript

import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        disableDefaultValidations: true,
      },
    },
  },
});

Deactivate default validation rules for one field

You can deactivate the default validation rule for a specific field by setting disableDefault to true. The following example deactivates the default validation rule for the firstName field.

Deactivate the default validation rule for the 'firstName' fieldJavaScript

import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        fields: {
          firstName: {
            validation: {
              disableDefault: true,
            },
          },
        },
      },
    },
  },
});

Set minimum and maximum length of a field

You can set the minimum and/or maximum length for a field with the maxLength and minLength validation rules. The following example sets the minimum length of the phone field to five characters and its maximum length to ten.

Set the minimum and maximum length of the 'phone' fieldJavaScript

import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        fields: {
          phone: {
            validation: {
              maxLength: {
                value: 10,
                message: 'Phone number must be a maximum of 10 characters.',
              },
              minLength: {
                value: 5,
                message: 'Phone number must be a minimum of 5 characters.',
              },
            },
          },
        },
      },
    },
  },
});

Make a field required or optional

You can set a field as required or optional with the required validation rule. The following example sets the phone field as required.

Set the 'phone' field as requiredJavaScript

import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        fields: {
          phone: {
            validation: {
              required: {
                value: true,
              },
            },
          },
        },
      },
    },
  },
});

Set the validation pattern for a field

You can set the validation pattern for a field with the pattern validation rule. The following example sets a validation pattern for the firstName field so that it accepts only capital letters as the first letter.

Set the validation pattern for the 'firstName' fieldJavaScript

import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        fields: {
          firstName: {
            validation: {
              pattern: {
                value: /^[A-Z]/,
              },
            },
          },
        },
      },
    },
  },
});

Set validation error messages

With the message validation rule, you can set error messages to be displayed if the value entered into a field does not meet its validation rule. The following example sets the error message that appears if the value entered in the firstName field does not begin with a capital letter.

Set the validation error message for the 'firstName' fieldJavaScript

import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        fields: {
          firstName: {
            validation: {
              pattern: {
                value: /^[A-Z]/,
                message: 'The name must begin with a capital letter.',
              },
            },
          },
        },
      },
    },
  },
});