Skip to content

Checkout layout handles

Can I join the Hyvä Checkout Beta?

Would you like to join the list of Beta participants?
Existing Hyvä customers and service integrators can contact us in Slack or email

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

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">
If a checkout does not inherit any configuration, it is called a base checkout.

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

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_defaut
  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 in the hyva-themes/checkout-default package at vendor/hyva-themes/checkout-default/src/view/frontend/layout/hyva_checkout_components.xml

<?xml version="1.0"?>
<page xmlns:xsi=""

        <!-- 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">
                    <argument name="magewire" xsi:type="object">Hyva\CheckoutCheck\Magewire\Example</argument>