Add a new field in address form
This topic describes how to add new fields to default checkout forms: shipping address or billing address form. For illustration we use a case of adding a field to the shipping address form.
Add the field to layout and handle its value on the client side
To add your custom field to the checkout address form and access its value on the client side, take the steps described further.
Add the field to layout. Both shipping address and billing address forms are generated dynamically. So to modify its layout, you need to create a plugin for the
Following is a sample logic for a plugin method adding a field named
Custom Attribute to the shipping address form:
This way, your field is added to the
customAttributes property of
'Magento_Checkout/js/model/new-customer-address.js, a JS object that lists all predefined address attributes and matches the corresponding server-side interface
customAttributes property was designed to contain custom EAV address attributes and is related to
\Magento\Quote\Model\Quote\Address\CustomAttributeListInterface::getAttributes method. The code above will automatically handle local storage persistence on frontend.
Optionally, instead of adding a plugin, you can use dependency injection (DI). For this, in
<your_module_dir>/Block/Checkout/ directory, add the
LayoutProcessor class adding the custom field to the address form. The class must implement the
\Magento\Checkout\Block\Checkout\LayoutProcessorInterface interface. You can use the code sample above as an example of the
\Magento\Checkout\Block\Checkout\LayoutProcessorInterface::process() method implementation. To add your
LayoutProcessor class the corresponding pool of processors, in the
<your_module_dir>/etc/frontend/di.xml file specify the following:
%path\to\your\LayoutProcessor% must be replaced by your real values.
Add a JS mixin to change the behavior of the component responsible for the data submission to the server side. For this, in your custom module, define a mixin as a separate AMD module that returns a callback function. Add the mixin file anywhere in the
<your_module_dir>/view/frontend/web directory. There are no strict requirements for the mixin file naming.
Following is a sample mixin modifying the behavior of
Magento_Checkout/js/action/set-shipping-information (this component is responsible for data submission between shipping and billing checkout steps):
When adding a field to the billing address form, you need to modify the behavior of one of the following components:
Magento_Checkout/js/action/set-payment-information, depending on when do you need the custom field valued to be passed to the server side. For example of a mixin, modifying one of these components, see the place-order-mixin.js in the Magento_CheckoutAgreements module.
Tell Magento to load your mixin for the corresponding JS component. For this, in the
<YourModule_dir>/view/frontend/ directory, add the
Following is a sample of such
requirejs-config.js for the sample mixin added earlier:
To add the field to the address model on the server side, add the
extension_attributes.xml file in the
Following is a sample
Access the value of the custom field on server side
If you took all the steps described in the previous paragraphs, Magento will generate the interface that includes your custom attribute and you can access your field value like this:
$value = $address->getExtensionAttributes()->getCustomField();