Customizing CSS classes

Styling in the Loki Checkout is handled via Tailwind CSS classes - for both Hyvä and Luma themes! This means that the PHTML templates actually contain the CSS classes to keep in the Tailwind CSS build, which again means that - normally - template overrides would be needed for the simplest thing. Loki Checkout tries to keep template overrides to a minimum. It does so by adding clever PHP utilities that allow you to modify various CSS classes in the XML layout instead.

Using the $css() utility

In every single PHTML template of the Loki Checkout, a new PHP variable $css is added which is actually an instance of the class \Yireo\LokiCheckout\Util\Block\CssClass which is invokable, as in, it behaves like a function:

$css('foobar')

The CSS classes you would add to this function will be outputted, unless they are actually overwritten in the XML layout. A real-life example usage of the utility might look like this:

File example.phtml:

<div class="<?= $css('field w-auto relative') ?>"></div>

By default, this will simply output the CSS classes as-is in the browser:

<div class="example field w-auto relative"></div>

Note that an additional CSS class example is automatically added as well, based on the XML layout name of the block that defined this template. (This only works if the scope is block which is explained later on.)

File loki_checkout.xml:

<block name="example" template="Yireo_LokiCheckout::example.phtml" />

Extending CSS classes

However, with the example above, we can also add new values easily as such. Take for example the prefix block:

<?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="color" xsi:type="string">bg-zinc-100 border border-zinc-200</item>
                    </item>
                </argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Within the item definition, the name color is actually not important, only the value of the item is important. And you can see that one item definition is able to hold multiple CSS classes.

Now the HTML will look like the following:

<div class="example field w-auto relative bg-zinc-100 border border-zinc-200"></div>

In short, first the block identifier, then the default CSS (which was passed from the PHTML template) and then the additional CSS from the XML layout.

Overriding CSS classes

What about overriding CSS classes? For this, it is important to know that the item name default can be used to override the default CSS (which was passed from the PHTML template).

<?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="default" xsi:type="string">field w-100 relative</item>
                        <item name="color" xsi:type="string">bg-zinc-100 border border-zinc-200</item>
                    </item>
                </argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Now the HTML will look like the following:

<div class="example field 100 relative bg-zinc-100 border border-zinc-200"></div>

Scoping CSS

What if you want to use the $css() utility multiple times in the same PHTML template? Then you need to add a scope. By default, the scope block is being used ($css('foobar', 'block')), but you can refer to other scopes easily. The following example defines a new scope inner-span:

<div class="<?= $css('field w-auto relative') ?>">
    <span class="<?= $css('text-xl', 'inner-span') ?>"></span>
</div>

Now, within the XML layout, the CSS classes of the inner-span scope can be extended like 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-step.shipping-address.prefix">
            <arguments>
                <argument name="css_classes" xsi:type="array">
                    <item name="inner-span" xsi:type="array">
                        <item name="default" xsi:type="string">text-2xl</item>
                    </item>
                </argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Scopes are only relevant when it comes to overriding or extending CSS classes via the XML layout.

Last modified: January 22, 2025