Skip to content

Styling Layout Containers

Background: Magento Layout Container Elements

Magento containers are rendered as HTML elements if the htmlTag attribute is specified in layout xml.

It also is possible to declare an htmlClass attribute.

If present, it will be rendered as a class attribute on the html element.

It is not a big leap to want to use this feature to add Tailwind CSS classes.

A downside to be aware of is that those classes are not picked up by the purge script, so unless they are also used in .phtml templates they will not be present in a production bundle, unless the XML files are added to the purge list (see below).

Valid Container CSS Class names

Still, this is fine, except that Magento limits the characters that are allowed for class names in the layout XML schema to a subset of actually valid class names.

Because of this, many Tailwind CSS class names lead to schema validation failures like the following example:

<container name="columns" htmlTag="div" htmlClass="columns order-2 w-1/3">
1 exception(s):
Exception #0 (MagentoFrameworkConfigDomValidationException): Element 'container', attribute 'htmlClass': [facet 'pattern'] The value 'columns order-2 w-1/3' is not accepted by the pattern '[a-zA-Z][a-zA-Zd-_]*(s[a-zA-Z][a-zA-Zd-_]*)*'.
Line: 13

Workaround 1: patch the schema pattern

There is a PR that got merged in Feb. 2023.
The change did not make it into the 2.4.6 release. Once it is released, this issue will no longer be relevant, but in the meantime Arjen Miedema supplied this patch (thanks!):

@package magento/framework

diff --git View/Layout/etc/elements.xsd View/Layout/etc/elements.xsd
index 51f1931..14baa00 100644
--- View/Layout/etc/elements.xsd
+++ View/Layout/etc/elements.xsd
@@ -119,7 +119,7 @@

     <xs:simpleType name="htmlClassType">
         <xs:restriction base="xs:string">
-            <xs:pattern value="[a-zA-Z][a-zA-Z\d\-_]*(\s[a-zA-Z][a-zA-Z\d\-_]*)*"/>
+            <xs:pattern value="[a-zA-Z\d\-_/:.\[\]&amp;@()! ]*"/>
         </xs:restriction>
     </xs:simpleType>

Workaround 2: add custom css to structure.css

Alternatively the basic structure of the page is styled in the Hyvä default theme file web/tailwind/components/structure.css.

Making changes to this file might also be a suitable customization approach.

Making Tailwind aware of classes in layout XML

There are three alternative approaches to make Tailwind aware of class names in layout XML files.

Option 1: Add the path to the layout XML to the purge config

In the tailwind.config.js, add the glob path pattern to the themes layout XML files to the configuration:

content: [
  // this theme's phtml files
  '../../**/*.phtml',
  // this theme's layout XML files
  '../../**/*.xml',
]

For Tailwind version 2 the path is purge.content, for version 3 it is only content

Option 2: Add the classes to the safelist

In the theme tailwind.config.js, add the desired classes to the safelist configuration:

  safelist: ['mt-10', 'md:mt-20']

For Tailwind version 2 the path is purge.safelist, for version 3 it is only safelist

Option 3: Add a dummy template with a comment containing the classes

For example, create a file Magento_Theme/layout-classes.phtml with the contents:

<?php
/* 
 * Tailwind CSS classes that should always be included in styles.css:
 * 
 * mt-10 md:mt-20
 */
The template does not need to be rendered or produce any output, it only needs to contain the desired classes.