# Customize the address forms of Checkout

Customize the address forms of your checkout experience.

Checkout's [default shipping and billing address forms](/checkout/custom-address-forms.md#default-address-forms) contain the [BaseAddress](/api/types.md#baseaddress) fields that are most frequently used in digital commerce.

However, you can [customize](/checkout/custom-address-forms.md#customize-the-address-form-layout) the layout of the address forms by adding, removing, and moving fields according to your needs. To do so, you can use both standard BaseAddress fields and [Custom Fields](/checkout/custom-address-forms.md#add-custom-fields).

You can also [customize](/checkout/custom-address-forms.md#customize-the-address-summary-layout) the layout of the address summary.

The billing address form inherits the configuration of the shipping address form. It is not possible to apply different customizations to the forms.

## 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](/checkout/hosts-and-authorization.md) 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](/checkout/browser-sdk.md#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.

```ts title="Syntax of the FormLayout type"
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](/api/types.md#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.

```javascript title="Add 'salutation', remove 'additionalStreetInfo', and move 'phone' fields"
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](/api/types.md#baseaddress) fields and [custom](/checkout/custom-address-forms.md#add-custom-fields) 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`.

```javascript title="Customize the standard 'salutation' field"
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](/api/types.md#address) data type in your Project. For further information, see the [API extensibility](/api/projects/types.md) documentation.
Checkout supports the following custom Types to extend your Address data type:

- [CustomFieldBooleanType](/search.md?urn=ctp:api:type:CustomFieldBooleanType)
- [CustomFieldStringType](/search.md?urn=ctp:api:type:CustomFieldStringType)
- [CustomFieldEnumType](/search.md?urn=ctp:api:type:CustomFieldEnumType)
- [CustomFieldNumberType](/search.md?urn=ctp:api:type:CustomFieldNumberType)
- [CustomFieldDateType](/search.md?urn=ctp:api:type:CustomFieldDateType)
- [CustomFieldTimeType](/search.md?urn=ctp:api:type:CustomFieldTimeType)
- [CustomFieldDateTimeType](/search.md?urn=ctp:api:type:CustomFieldDateTimeType)

After extending the Address data type, you must include the field keys in the [`forms.default.address.layout`](/checkout/custom-address-forms.md#customize-the-address-form-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 the API. Otherwise, an error is returned 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](/checkout/custom-address-forms.md#customize-address-fields) 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.

```javascript title="Add Custom Fields to the address form"
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](/checkout/browser-sdk.md#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.

```ts title="Syntax of the AddressSummaryLayout type"
type AddressSummaryLayout = Array<Array<string | [string, string]>>;
```

```javascript title="Customize the address summary"
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](/checkout/custom-address-fields-validation.md).

## Related pages

- [Area overview page with navigation](/checkout.md)
- [Previous page: Texts and labels](/checkout/custom-texts-labels.md)
- [Next page: Address fields validation](/checkout/custom-address-fields-validation.md)
- [Search documentation and API specs](/search.md)