This topic describes how to add a custom input form (implemented as a UI component) to the Checkout page.
Most of the elements, including the default forms on the Checkout page are implemented as UI components. And we recommend your custom form to be a UI component, extending the default Magento_Ui/js/form/form component.
Magento provides the ability to add a custom form to any of the checkout steps: Shipping Information, Review and Payment Information, or custom. In order to add a custom form that is a UI component, take the following steps:
For the sake of compatibility, upgradability, and easy maintenance, do not edit the default Magento code. Instead, add your customizations in a separate module. For your checkout customization to be applied correctly, your custom module should depend on the Magento_Checkout module. Do not use Ui for your custom module name, because %Vendor%_Ui notation, required when specifying paths, might cause issues.
Create the JS implementation of the form UI component
In your <your_module_dir>/view/frontend/web/js/view/ directory, create a .js file implementing the form.
Example of extending the default form component:
Create the HTML template
Add the knockout.js HTML template for the form component under the <your_module_dir>/view/frontend/web/template directory.
Modifying the custom template after it was applied
If you modify your custom .html template after it was applied on the store pages, the changes will not apply until you do the following:
Delete all files in the pub/static/frontend and var/view_preprocessing directories.
Reload the pages.
Declare the form in the checkout page layout
Certain default checkout templates declare regions where additional content can be inserted. You can add your custom form in any of these regions. These regions are provided with corresponding comments in the default Checkout page layout file <Checkout_module_dir>/view/frontend/layout/checkout_index_index.xml.
Also you locate the regions in the .html templates of the blocks used in this layout file.
For example, the shipping JS component (see <Magento_Checkout_module_dir>/view/frontend/web/template/shipping.html) provides the before-form region and corresponding UI container.
Any content added here is rendered before the Shipping Address form on the Shipping Information step. To add content to this region, create a checkout_index_index.xml layout update in the <your_module_dir>/view/frontend/layout/. It should be similar to the following:
The term static refers to the forms where all the fields are already known/predefined and do not depend on any settings in the Admin. (compare to dynamic forms)
The fields of static forms are not generated dynamically, so they can be defined in a layout.
The following code sample shows configuration of the form that contains four fields: text input, select, checkbox, and date. This form uses checkout data provider (checkoutProvider) that is introduced in the Magento_Checkout module:
Dynamically defined forms
Dynamically defined, or dynamic, forms are the forms where the set or type of fields can change. For example, the fields displayed on the checkout form depend on the Admin settings: depending on the Admin > Stores > Configuration > Customers > Customer Configuration > Name and Address Options
For such forms, you must implement a plugin for the \Magento\Checkout\Block\Checkout\LayoutProcessor::process method.
A plugin can add custom fields definitions to layout at run-time. The format of the field definition is the same as for fields defined in layout.
If you use the code samples provided as examples in this topic, this would result in adding the following form to the Shipping Information step: