Skip to content

Checkout layout handles

The contents of layout steps are declared in Magento layout XML files.
For each checkout step, a number of layout handles are available.

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 from a parent checkout configuration.

If a checkout has a parent, it is called a child checkout configuration. This is the most common scenario.

<checkout name="my-child-checkout" label="A Child Checkout" parent="default">
    ...
</checkout>
If a checkout does not inherit any configuration, it is called a 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 (for example the Hyvä Default checkout), the following layout handles are available:

  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

If a checkout has a parent, the parent layout handles will be included, too, so the full list looks like this:

  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 by using <update handle="..."/> within a <step/> configuration.

The hyva_checkout_components handle

The hyva_checkout_components is used to declare components that are used in more than one step.
Such reusable components are declared as children of a hyva.checkout.components block.

Note this hyva.checkout.components block is not rendered. Its purpose is to serve as a virtual container for checkout component declarations, which then can be injected into the respective steps using the <move name=""> directive.

You can see an example of this 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>