Magento 2 UI Grid Component

- Fire development, Magento 2

Magento 2 Development

There is a great explanation of Magento 2 UI Component Grid on StackExchange (the link to the original answer is provided below). Below, we provide its major aspects. The official devdoc is here: Overview of UI components.


layout file from Company/Module/view/adminhtml/layout/module_controller_action.xml defines grid as uiComponent via:


uiComponent is defined in the Company/Module/view/adminhtml/ui_component/listing_name.xml file. Note that the file name should be the same as uiComponent name from an appropriate layout file. The structure of the file always have some repeating nodes, so it is not as complex as you may think after the first review.

Main node of the component file:

<listing xmlns:xsi=”” xsi:noNamespaceSchemaLocation=”urn:magento:module:Magento_Ui:etc/ui_configuration.xsd”>

Next, there are 4 nodes inside the <listing /> node:

<argument />, <dataSource />, <container /> and <columns />

Note that it isn’t a strict setup since the <argument /> node might be duplicated for providing additional configuration or <container /> as in CMS page listing (adding “sticky” container).

The <argument /> node:

  • The <argument /> node requires attribute name. In this case data specifies basic information about the component. It contains multiple <item /> nodes for each specific part of the configuration. Thus, js_config tells the component where the provider of the data and dependencies in the listing xml configuration are.
  • provider value consist of listing name used in layout file and uniqure data source name that will be used later. provider and deps are the same.
  • spinner takes name of the node where columns of the grid are defined.
  • buttons allows to add buttons to the top of the grid. They have few elements: name used as element id, label is what the button says, class is the button class, and url is the link to which it points. Asterisk is replaced by the portion of current url. Other possible <item /> nodes for button: id, title, type (reset, submit or button), onclick(instead of url, it has precedence), style, value, disabled. Button element is rendered by Magento\Ui\Component\Control\Button class.

The <dataSource /> node:

name used in <dataSource /> node must match the one used in argument/js_config/providerand argument/js_config/deps. Next node defines which class is responsible for preparing data for the grid. class argument requires unique name that will be matched in di.xml. primaryFieldName relates to the database primary column and requestFieldName to the variable in http requests. They may be equal but don’t have to, CMS page listing uses page_id as primaryFieldName and id as requestFieldName. update_url refers to the entry point where ajax calls for filtering and sorting are send. Second argument in <dataSource /> refers to javascript file that handles js part of sending and processing ajax calls for the grid. The default file is Magento/Ui/view/base/web/js/grid/provider.js.

The <container /> node

As it contains a lot of data let me divide it as well. Its children are the parts of the entire page. First child <argument />:

It defines knockout template responsible for handling the layout and all actions and by default points to Magento/Ui/view/base/web/templates/grid/toolbar.html

The <bookmark /> node

This node adds bookmark feature to the grid. It allows admin to set up different “profiles” of the grid which displays different columns. Thanks to that you can add all columns from the table to the grid and let the user decide which information are relevant to him. namespace must match name used in layout file.

The <component /> node

We have 3 values to configure here:

  • First is provider which follows the pattern [listing_name_from_layout].[listing_name_from_layout].[listing_columns_node_name] (like in node listing/argument/spinner).
  • component refers to js file that displays grid and by default points to Magento/Ui/view/base/web/js/grid/controls/columns.js which uses template  Magento/Ui/view/base/web/templates/grid/controls/columns.html.
  • The last item is displayAreawhich defines where column controls need to be displayed. It refers to getRegion(‘dataGridActions’) in file defined in  container/argument/config/template .

The  <filterSearch /> Node

This node adds full text search into the page. It is located above the grid as single text input field with “Search by keyword” as a placeholder. I am not sure what options are possible here as I didn’t play with this much but listing_filters_chips refers to  Magento/Ui/view/base/web/js/grid/filters/chips.js file.

The <filters /> node

This node defines configuration for column filtering that is visible after clicking “Filters” button at the top right above the grid.

  • columnsProvider follows similar structure as previous nodes, so [listing_name_from_layout].[listing_name_from_layout].[listing_columns_node_name].
  • storegeConfig goes like [listing_name_from_layout].[listing_name_from_layout].[container_node_name][bookmark_node_name].
  • In templates item node you can define which files are used to render specific filter options. In this case only select is defined and it uses Magento/Ui/view/base/web/js/form/element/ui-select.js as component and  Magento/Ui/view/base/web/templates/grid/filters/elements/ui-select.html as knockout template. Look into Magento/Ui/view/base/web/js/form/element to see other possibilities. Only select is defined here to override default values:  Magento/Ui/view/base/web/js/form/element/select.js and Magento/Ui/view/base/web/templates/grid/filters/elements/select.html.  Default values for filters and other nodes are defined in  Magento/Ui/view/base/ui_component/etc/definition.xml.

The <massAction /> node

name argument should be unique.

  • First child node <argument /> defines basic data.
  • provider follows the same structure as other nodes and refers to columns node name and its ids column. This column will hold checkboxes with selected items for the mass action to process.
  • componentdefines what file is used to render and handle the mass action.
  • Default value is Magento_Ui/js/grid/massactions (points to Magento/Ui/view/base/web/js/grid/massactions.js). You can use Magento_Ui/js/grid/tree-massactions to add tree like structure. In the above case I use it to add “Change status” action which shows “enable” and “disable” options. After <argument /> node you can add as many <action /> nodes as many actions you want to have. Each <action /> node follows similar scheme. In the first case (delete action) node requires unique name. Then argument contains configuration where label is what is visible in select option, url endpoint to send data and confirm adds confirmation modal before send. In case of “Change status” action url in first argument node is omitted as urls are provided per status by class defined in second argument node. The class should implement Zend\Stdlib\JsonSerializable interface. Check Magento\Customer\Ui\Component\MassAction\Group\Options as a reference.

The <paging /> node

Structure for provider and selectProvider should be clear now.

The <columns /> node

and the name attribute is used in other nodes when refers to it. First child is

supply correct provider values following the scheme used in the listing. The fieldAction node allows to define action that is fired when clicked on the cell. Default settings call edit action.

<selectionColumns />

This node defines column with checkboxes for mass action to use. It names is referred to after dot in several nodes described above.

After that you can add any number of columns in the same format:

Not all most inner items node are necessary. They are defining:

  • filter – filter type of the column.
  • component – defines js files which is used to render column.
  • dataType – provides information of data type used for the column value.
  • label – this will be displayed in the column header and filter block.
  • sortOrder – ordering.
  • visible – whether or not display the column.

At the end you can add actions column witch actions available to do for the single item

indexField refers to column name in the database. Actions class should extends Magento\Ui\Component\Listing\Columns\Column and define prepareDataSource method. See Magento/Cms/Ui/Component/Listing/Column/PageActions.php as a reference


to finish the grid we need to define some elements in Company/Module/etc/di.xml

define provider class used in node dataSource/class

collection resolves to standard collection class and filerPool defines new element:

register our data source:

node name must match the one used in <dataSource /> node in listing xml and it resolves not to collection but to GridCollection class. It should extend regular collection class and additionally implement Magento\Framework\Api\Search\SearchResultInterface.

configure grid collection (argument names are rather obvious)

More tips from Magento 2 Cookbook

Source (Magento Stackexchange Question) (Zefiryn, Vinai)