Checkout layout handles

Hyvä Checkout uses Magento layout XML handles to define the content of checkout steps. Each checkout step has a specific set of layout handles available, allowing you to configure components, forms, and other UI elements that appear within the step.

Layout handles follow a hierarchical structure that supports configuration inheritance. Child checkouts inherit layout handles from their parent checkout, enabling efficient reuse of common configurations while allowing step-specific customizations.

Layout XML and Module Sequence

When declaring Checkout related layout XML inside a module, be sure to add Hyva_Checkout to the <sequence> of your modules etc/module.xml file, so the base layout provided by the checkout module is evaluated before your custom layout declarations.

<module name="My_Module">
    <sequence>
        <module name="Hyva_Checkout"/>
    </sequence>
</module>

This is not necessary for theme-based Checkout related layout XML.

Base checkouts and child checkouts

Checkouts can inherit configuration from a parent checkout using the parent attribute. This inheritance model affects which layout handles are available during rendering.

A child checkout configuration inherits from a parent checkout. Child checkouts are the most common scenario and use the parent attribute to specify their parent. This example shows a child checkout that inherits from the "default" checkout:

<checkout name="my-child-checkout" label="A Child Checkout" parent="default">
    ...
</checkout>

A base checkout does not inherit any configuration and serves as the foundation for child checkouts. Base checkouts omit the parent attribute. This example shows the Hyvä default base checkout:

<checkout name="default" label="Hyvä Default" layout="2columns">
    ...
</checkout>

List of layout handles

Base checkout handles

For base checkouts without a parent checkout configuration (such as the Hyvä Default checkout), the following layout handles are available and processed in this order:

1. hyva_checkout_components
2. hyva_checkout_layout_<step-layout>, e.g. hyva_checkout_layout_2columns
3. hyva_checkout_<checkout-name>, e.g. hyva_checkout_default
4. hyva_checkout_<checkout-name>_<step-name>, e.g. hyva_checkout_default_login

Child checkout handles

When a checkout has a parent, the parent layout handles are included first, followed by the child-specific handles. This allows child checkouts to inherit and extend parent configurations. The complete list of layout handles for child checkouts is processed in this order:

1. hyva_checkout_components
2. hyva_checkout_layout_<step-layout>, e.g. hyva_checkout_layout_2columns
3. hyva_checkout_<checkout-parent-name>, e.g. hyva_checkout_default
4. hyva_checkout_<checkout-parent-name>_<step-name>, e.g. hyva_checkout_default_login
5. hyva_checkout_<checkout-name>, e.g. hyva_checkout_custom
6. hyva_checkout_<checkout-name>_<step-name>, e.g. hyva_checkout_custom_login

Custom layout handles can be included conditionally using <update handle="..."/> within a <step/> configuration in hyva_checkout.xml.

The hyva_checkout_components handle

The hyva_checkout_components layout handle is used to declare reusable checkout components that appear in multiple steps. Reusable components are defined as children of the special hyva.checkout.components container block.

The hyva.checkout.components block is not rendered directly. It serves as a virtual container for checkout component declarations, which can then be injected into specific steps using the <move name=""> layout directive. This approach avoids duplicating component definitions across multiple step-specific layout files.

The following example demonstrates how to declare a reusable component in the hyva_checkout_components handle. This example is from the Hyvä Checkout module at vendor/hyva-themes/magento2-hyva-checkout/src/view/frontend/layout/hyva_checkout_components.xml:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>

        <!-- Either declare component blocks as children of a section container -->
        <!-- or as direct children of the hyva.checkout.components block -->

        <referenceContainer name="checkout.shipping-details.section">
            <block name="hyva-checkout-example">
                <arguments>
                    <argument name="magewire" xsi:type="object">Hyva\CheckoutCheck\Magewire\Example</argument>
                </arguments>
            </block>
        </referenceContainer>
    </body>
</page>

Once declared in the hyva_checkout_components handle, these components can be moved into specific checkout steps using standard Magento layout XML <move> directives in step-specific layout handles.