Changing the grid of field blocks

This tutorial extends from the previous one, which explained the $css() utility.

The (billing and/or shippping) address form is using CSS grids (of 12 columns) to put all fields in the right place. Each field is a Magento block (so, a <block> within the XML layout). And because the outer <div> HTML element (as found within the PHTML template for each field, like form/field.phtml) is using the $css() utility, this can be used to style each field.

Changing the grid (the ugly way)

For instance, the prefix field can be given a column span 2 in the 12 column grid system:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:View/Layout:etc/page_configuration.xsd">
    <body>
        <referenceBlock name="loki.checkout.shipping-step.shipping-address.prefix">
            <arguments>
                <argument name="css_classes" xsi:type="array">
                    <item name="block" xsi:type="array">
                        <item name="grid" xsi:type="string">col-span-2</item>
                    </item>
                </argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Likewise, by using the XML layout <move/> directive, you can move each field in the right position.

However, this becomes pretty cumbersome if you need to do this for all fields. There is a better way instead.

Using the etc/loki_checkout.xml configuration file

The module LokiCheckout_Core ships with a file etc/loki_checkout.xml which configures a sorting order and CSS grid classes. This looks similar to the following:

<?xml version="1.0" encoding="UTF-8" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:LokiCheckout_:etc/loki_checkout.xsd">
    <grid_layout name="default_grid">
        <grid name="default">
            <block alias="prefix" sortOrder="1" gridClass="col-span-6"/>
            <block alias="firstname" sortOrder="2" gridClass="col-span-6"/>
            <block alias="middlename" sortOrder="3" gridClass="col-span-6"/>
            ...
        </grid>
    </grid_layout>
</config>

This XML configuration is used by a ViewModel LokiCheckout\Util\Block\GridBlock to adjust child blocks identified by their XML layout block alias (<block name="..." as="prefix">). For example, the PHTML template checkout/billing/address-form.phtml makes use of this:

/** @var \LokiCheckout\Factory\ViewModelFactory $viewModelFactory */
/** @var \LokiCheckout\Util\Block\GridBlock $gridBlock */
$gridBlock = $viewModelFactory->create(GridBlock::class);

And:

<?php foreach ($gridBlock->getChildren($block) as $childBlock): ?>
    <?= $childBlock->toHtml() ?>
<?php endforeach; ?>

Different grid layouts

The default grid layout is called default_grid, but other grid layouts can be created as well. For instance, the LokiCheckout_Nl module introduces a grid layout called dutch_grid and the LokiCheckout_PostcodeNl modules introduces a grid layout called postcode_nl_grid. Just search for any etc/loki_checkout.xml file in your system.

You can also add your own grid layout if you want by adding a etc/loki_checkout.xml to a custom Magento module:

<?xml version="1.0" encoding="UTF-8" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:LokiCheckout_:etc/loki_checkout.xsd">
    <grid_layout name="custom_grid">
        ...
    </grid_layout>
</config>

The grid layout is applied to a certain form via the XML layout.

For instance, the layout file loki_checkout_block_billing_address.xml could look as follows:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:View/Layout:etc/page_configuration.xsd">
    <body>
        <referenceBlock name="loki-checkout.billing-address.address-form">
            <arguments>
                <argument name="grid_layout" xsi:type="string">custom_grid</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

And similarly, the layout file loki_checkout_block_shipping_address.xml could look as follows:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:View/Layout:etc/page_configuration.xsd">
    <body>
        <referenceBlock name="loki-checkout.shipping-address.address-form">
            <arguments>
                <argument name="grid_layout" xsi:type="string">custom_grid</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Grids per country

The etc/loki_checkoutxml file also allows for a grid layout to have different settings per country. For instance, take the following snippet from the core:

<?xml version="1.0" encoding="UTF-8" ?>
<config ...>
    <grid_layouts>
        <grid_layout name="default_grid" ... defaultMdColSpan="6">
            <grid name="default">
                ...
                <block alias="country_id" sortOrder="120" />
                ...
            </grid>
            <grid name="netherlands" countryId="NL" parent="default">
                <block alias="country_id" mdColSpan="12"/>
            </grid>
        </grid_layout>
    </grid_layouts>
</config>

Here, the grid layout default_grid contains a grid default that defines the country field to have a md:col-span-6 CSS class. However, when the country is NL (The Netherlands), this changes to md:col-span-12.

About the Tailwind order-* classes

Each field is ordered within the HTML following these grid layout settings. In other words, the default HTML document resembles the final ordering of all blocks. That being said, the same HTML contains Tailwind order-* classes.

These CSS classes only serve a single purpose: When the country is changed (for instance, from Germany to The Netherlands), the grid settings could lead into a different layout.

Last modified: August 13, 2025