Magento 2: changing custom theme default layout

Magento 2: changing custom theme default layout

July 23, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento 2: changing custom theme default layout

Changing Default Layout in Magento 2 Custom Theme

Hello developers! I hope this post finds you well. Today, we’re going to dive into an interesting question about Magento 2 theme customization.

The Challenge: Setting the Default Layout

You have a custom theme that doesn’t inherit from any parent theme in Magento. Your default layout appears to be 1column, and you’ve successfully made modifications to this column in your custom theme’s layout\default.xml file.

However, you want the default layout for your theme to be 2columns-left. You’ve noticed that in Magento’s built-in themes, this is achieved by adding the layout attribute to the page element in default.xml.

Your Directory Setup

Your custom theme directory looks like this:

/Metal
  /bronze
    /Magento_Theme
      /layout
        default.xml
        default_head_blocks.xml
      /page_layout
        1column.xml
        2columns-left.xml
    /media
      ...
    /web
      ...
    composer.json
    registration.php
    theme.xml

Your default.xml File

Here’s your current default.xml file:

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

The Issue

You’ve noticed that when you try to set the default layout to 2columns-left, none of your defined containers render on the page. This means you can’t move elements like the newsletter block to the sidebar, as you intended.

What’s Going Wrong?

The issue lies in how Magento handles theme layouts. By default, it expects a specific structure and naming convention for your layout XML files.

When you set layout="2columns-left" at the page level, Magento is looking for a file named 2columns-left.xml in the following directory:

/app/design/frontend/<Vendor>/<Theme>/Magento_Theme/layout/page_layout/

In your case, this file exists under /Metal/bronze/Magento_Theme/page_layout/, but Magento is not finding it because of the different folder structure you’ve set up.

The Solution

To fix this issue, you need to update your theme.xml file to map the 2columns-left layout handle correctly.

  1. Open your theme.xml file located in /Metal/bronze/theme.xml.

  2. Look for the <layout> element under <preference for="Magento_Theme" />. It should look something like this:

<layout>
    <update handle="empty"/>
</layout>
  1. Update it to include a reference to your 2columns-left.xml file:
<layout>
    <referenceContainer name="root">
        <container name="content" as="content_area">
            <block type="core/text_list" name="content" as="content_area"/>
        </container>
    </referenceContainer>
    <update handle="empty"/>
</layout>
  1. Save the file and clear your cache by running php bin/magento cache:clean in your terminal.

The Key Takeaway

In Magento, the default layout is determined by the theme.xml file’s mapping to layout handles, not directly from the default.xml file as you might initially think. Always ensure that the layout handle names match the XML files’ actual locations for theming to work correctly.

Is Posting in Multiple Places a Violation?

No, there is no etiquette violation in posting your question to both Magento Community and our platform. We’re here to help! The more exposure your question gets, the higher the chance of getting a helpful answer from someone with relevant experience.

Remember, the key is to provide context when you post in multiple places (like including all your code snippets) so that people can understand your situation without having to read through multiple threads.

Conclusion

Changing the default layout in Magento 2 custom themes involves mapping the layout handles correctly in the theme.xml file. Always ensure that the XML files for your layouts are named and located as expected by Magento’s naming conventions.

If you found this post helpful, feel free to explore our other Magento-related articles on Laravel Company. We cover a wide range of topics from theme customization to advanced development techniques.

Happy coding!

Magento 2 API Themes Configuration

Our network