Skip to content

Page Builder Default Classes

Since Hyvä Theme 1.5.4, the Hyva_Theme module adds CSS classes to Page Builder content when it is rendered in a Hyvä theme. This lets Page Builder elements use the Hyvä component classes, such as btn and prose, without restyling the Page Builder classes in your theme CSS. The classes are configured in di.xml, so you can add classes to more elements, or switch a default off.

Why the Classes Are Added at Render Time

Page Builder saves its content as HTML in the database. The Page Builder templates are only used in the admin editor, so changing them would only affect content that is created or saved again after the change.

The Hyva_Theme module adds the classes when the content is rendered instead. This has a few advantages:

  • Existing content is included: all Page Builder content gets the classes, without saving it again in the admin.
  • The classes stay out of the database: the content stays theme independent, so a Luma store view or a headless frontend that renders the same content doesn't get Hyvä classes.
  • Page Builder stays optional: the classes are added by a plugin on the Page Builder template filter, which only runs when Page Builder is installed. There is no Composer dependency on Page Builder.
  • Changes take effect on the next render: there is no content to migrate when you change the configuration.

Default Classes

The Hyva_Theme module adds the following classes by default.

Element Matched by Classes added
Primary button class pagebuilder-button-primary btn btn-primary
Secondary button class pagebuilder-button-secondary btn btn-secondary

The classes are added next to the existing classes, so the Page Builder classes stay available for your own styles.

Configuring the Classes

The classes are set with two arguments of Hyva\Theme\Model\PageBuilderDefaultClasses. Both accept any Page Builder element.

classesByContentType
Classes keyed by the data-content-type value of the element, for example text, image or divider. The classes are added to the outer element of the content type, which carries the data-content-type attribute.
classesByCssClass
Classes keyed by a class the element already has, for example pagebuilder-button-primary or pagebuilder-banner-button. Use this argument for elements inside a content type that have their own Page Builder class.

The value of each item is a space separated list of classes. Classes that are already on the element are not added twice.

Add the configuration to etc/frontend/di.xml in a custom module. Add Hyva_Theme to the <sequence> in the etc/module.xml of the module, so its configuration is merged after the defaults.

Opting In to More Classes

The following example adds prose to Page Builder text, so headings, paragraphs and lists in text elements get the Hyvä typography styles. It also adds btn to link buttons, so they get the same size and spacing as the other buttons.

app/code/Vendor/Module/etc/frontend/di.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Hyva\Theme\Model\PageBuilderDefaultClasses">
        <arguments>
            <argument name="classesByContentType" xsi:type="array">
                <item name="text" xsi:type="string">prose</item>
            </argument>
            <argument name="classesByCssClass" xsi:type="array">
                <item name="pagebuilder-button-link" xsi:type="string">btn</item>
            </argument>
        </arguments>
    </type>
</config>

Check existing content after opting in

New classes change how existing Page Builder content looks on every page that uses it. For example, prose adds spacing and typography to text that may already be styled with Tailwind classes in the content. Review your CMS pages and blocks before enabling the classes on a live store.

Switching a Default Off

To keep the previous styling of an element, set its item to xsi:type="null" in your own di.xml. An empty string doesn't work, because Magento keeps the original value when the merged item is empty.

app/code/Vendor/Module/etc/frontend/di.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Hyva\Theme\Model\PageBuilderDefaultClasses">
        <arguments>
            <argument name="classesByCssClass" xsi:type="array">
                <item name="pagebuilder-button-secondary" xsi:type="null"/>
            </argument>
        </arguments>
    </type>
</config>

Compiled dependency injection

In production mode, and in any mode once bin/magento setup:di:compile has run, the di.xml arguments are read from the compiled configuration. Run bin/magento setup:di:compile again after changing the classes.

Limitations

  • Only elements with a matching attribute or class: classes can be added to the element with the data-content-type attribute, or to elements with a known class. Inner elements without their own class, such as the img inside an image content type, can't be targeted.
  • Headings share one content type: all Page Builder headings use data-content-type="heading", so you can't add different classes per heading level. The prose class also only styles the elements inside it, so adding it to a heading has no effect on the heading itself. Style Page Builder headings in your theme CSS instead.
  • Double quoted attributes only: Page Builder always writes double quoted attributes. Hand written HTML in an HTML Code element with single quoted attributes is not matched.