Customize the address forms of Checkout

Default address forms

Checkout's default shipping and billing address forms contain the following fields in the following order:

• firstName - Required
• lastName - Required
• email - Required
• country - Required
• streetName - Required
• streetNumber - Optional (displayed for Europe Region only)
• additionalStreetInfo - Optional
• postalCode and city - Required (displayed for Europe Region only)
• city - Required (displayed for North America and Australia Regions only)
• state and postalCode - Required (displayed for North America and Australia Regions only)
• phone - Optional
• company - Optional

Customize the address form layout

To customize the layout of the address form, you must pass the forms.default.address.layout object with the checkoutFlow method when initializing Checkout.

The forms.default.address.layout object must contain an array of arrays of strings, where the outer array represents the address form, each inner array represents a row of the form, and each string represents a field.

type FormLayout = Array<Array<string>>;

Add, remove, and move standard fields

To customize the layout of the address forms with standard fields, you can add or remove any BaseAddress field, except the required country field. You can also change the order of fields.

The following example adds a row with the salutation field, removes the row with the additionalStreetInfo field, and moves the row with the phone field.

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

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        layout: [
          ['salutation'],
          ['firstName'],
          ['lastName'],
          ['email'],
          ['phone'],
          ['country'],
          ['streetName'],
          ['streetNumber'],
          ['postalCode', 'city'],
          ['company'],
        ],
      },
    },
  },
});

Customize address fields

For both standard BaseAddress fields and custom fields, you can customize the label, the initial value, and the component type used to render the field. Checkout supports the following component types:

• text
• checkbox
• radio
• select
• email
• number
• tel
• date
• time
• datetime
• url

These customization options are mainly useful for custom fields, but you can also use them for standard fields.
For example, you might want to limit the values of the standard salutation field to two. In such case, you will need to render the field as a drop-down (using the select component type) or as radio buttons (using the radio component type). For your drop-down or radio buttons, you must then set the possible values by providing an array of valueOptions with related pairs of value and label. Finally, you could set the value which is initially selected, by setting initialValue.

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

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        fields: {
          salutation: {
            label: 'Mr/Mrs',
            componentType: 'select',
            valueOptions: [
              {
                value: 'mr',
                label: 'Mr.',
              },
              {
                value: 'mrs',
                label: 'Mrs.',
              },
            ],
            initialValue: 'mr',
          },
        },
      },
    },
  },
});

Add custom fields

To add custom fields to the address form, you must extend the Address data type in your Project. For further information, see the API extensibility documentation.
Checkout supports the following custom Types to extend your Address data type:

• CustomFieldBooleanType
• CustomFieldStringType
• CustomFieldEnumType
• CustomFieldNumberType
• CustomFieldDateType
• CustomFieldTimeType
• CustomFieldDateTimeType

After extending the Address data type, you must include the field keys in the forms.default.address.layout object and provide a forms.default.address.custom object containing the following:

• type.key - Object containing a string
  The key of the custom Type that you used to extend your Address data type.

• fields - Object containing other objects
  It contains an object per custom field. Each object contains the following:

  • CUSTOM_FIELD_NAME - Object containing the following:

    • label - String
      The label of the custom field. Custom fields don’t have a default label, if you don't set one, the field will render without any label.
    • customType - String
      The custom Type associated with the custom field. It is required to convert the value into the correct field type before sending data to Composable Commerce. Otherwise, Composable Commerce will generate an error if, for example, you try to store a String value in a Boolean field.
      If you don’t set a value for customType, it will be set to String by default.
    • componentType - String
      The component type used to render the custom field. Although you can select any component type for any custom field, we recommend choosing the component type that best suits your use case, depending on the customType of the field. For example, using a checkbox component type for a Boolean field, a radio or a select component type for an Enum field, or a date component type for a Date field.
    • valueOptions - Array of objects
      The possible values for a custom field which is rendered with a radio or select component type. In any other case, this will be ignored.

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

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        layout: [
          ['firstName', 'lastName'],
          ['email'],
          ['country'],
          ['example-boolean-field'],
          ['example-string-field'],
          ['example-enum-field'],
          ['example-number-field'],
          ['example-date-field'],
          ['example-time-field'],
          ['example-datetime-field'],
        ],
        custom: {
          type: {
            key: '{customTypeKey}',
          },
          fields: {
            'example-boolean-field': {
              label: 'Custom Boolean Field',
              customType: 'Boolean',
              componentType: 'checkbox',
            },
            'example-string-field': {
              label: 'Custom String Field',
              customType: 'String',
            },
            'example-enum-field': {
              label: 'Custom Enum Field',
              customType: 'Enum',
              componentType: 'radio',
              valueOptions: [
                {
                  value: 'one',
                  label: 'One',
                },
                {
                  value: 'two',
                  label: 'Two',
                },
              ],
              initialValue: 'one',
            },
            'example-number-field': {
              label: 'Custom Number Field',
              customType: 'Number',
              componentType: 'number',
            },
            'example-date-field': {
              label: 'Custom Date Field',
              customType: 'Date',
              componentType: 'date',
            },
            'example-time-field': {
              label: 'Custom Time Field',
              customType: 'Time',
              componentType: 'time',
            },
            'example-datetime-field': {
              label: 'Custom DateTime Field',
              customType: 'DateTime',
              componentType: 'datetime',
            },
          },
        },
      },
    },
  },
});

Customize the address summary layout

After your customer fills in the address form, a summary of the address data is displayed. You can customize the address summary by selecting which fields to include and in which order.
To customize the address summary, you must add a forms.default.address.summaryLayout object to the checkoutFlow method when initializing Checkout.

The forms.default.address.summaryLayout must contain an array of arrays of strings (or tuples of [string, string]), where the outer array represents the summary, each inner array represents a row of the summary, each string represents a field, and each tuple represents a pair of field and label.
Because labels are not rendered in the address summary, you can use tuples of strings to render a field and the related label. For example, you can render the postalCode field with the ZIP label.
You can add both standard and custom fields to the summary layout.

type AddressSummaryLayout = Array<Array<string | [string, string]>>;

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

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  forms: {
    default: {
      address: {
        summaryLayout: [
          ['salutation', 'firstName', 'lastName'],
          ['email'],
          ['streetName', 'streetNumber'],
          [['postalCode', 'ZIP'], 'city'],
          ['country'],
          ['additionalStreetInfo'],
        ],
      },
    },
  },
});

Customize validation of address form field

You can customize the frontend validation rules for the address form fields. For further information, see Address fields validation.