Declare a custom UI component
Declaring a custom UI component refers to creating the XML configuration of your custom component, and is a part of a bigger task of creating a custom UI component.
This topic describes the XML elements that must be used for declaring a custom component and where this declaration should be placed.
XML elements used for declaring the custom component
A custom UI component can be declared using one of the following elements:
<component> element is typically used for declaring simple custom components that do not have other nested components.
<component> uses the uiElement constructor by default.
<container> element is typically used for declaring custom components that are collections, or in other words, can have nested components.
<container> uses the uiCollection constructor by default.
Attributes you can use
<component> elements have no mandatory attributes. The following optional attributes are available for both these elements:
class: link to the component’s PHP class.
template: link to component’s
provider: link to component’s data provider.
sortOrder: component’s sort order
displayArea: the placeholder which defines the area for rendering the component in the layout file.
If the following elements are used inside
<component>, they should be specified strictly in the following order:
For the component configuration inside
<component>, use the “arbitrary” structure.
Declare a custom basic component
If the custom component you create is a basic UI component (like Form or Listing), you need to take the following steps to declare it:
- Specify the XML file with its configuration it in the page layout file in your module, as described in the About XML сonfiguration of UI сomponents topic.
- Declare the component in a separate
.xmlfile using the
<component>as parent node.
Declare a custom secondary component
If the custom component you create is secondary (not a basic one), it is declared using
<component> in the XML configuration file of the basic component.
Example: Creating a custom secondary (not basic) component
Task: In the Customer form, replace the select field with a custom UI component. The custom component extends the Select component by adding a custom option that enables custom functionality.
The Customer form configuration is defined in
<Magento_Customer_module_dir>/view/base/ui_component/customer_form.xml. The default configuration of the select field we will extend is following:
The custom component we create extends Select, and is also a simple component (does not have child components), so we use the
<component> element for its declaration. To add the declaration, we need to create the
customer_form.xml file in the custom module, and put it in the same location relative to the module directory as the original
customer_form.xml resides. So the custom form configuration file will be:
We copy the
<field> configuration, remove the
<select> node and its configuration, and replace it with
<component> and its configuration: