Magento XML - Difference cms_index_index and cms_index_defaultindex

Magento XML - Difference cms_index_index and cms_index_defaultindex

August 29, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento XML - Difference cms_index_index and cms_index_defaultindex

Understanding Magento XML Layout Handles: cms_index_index vs. cms_index_defaultindex

As you delve into the depths of Magento development, you’ll often find yourself navigating through the labyrinth of XML layout files to modify your store’s behavior and appearance. Two common handles you might encounter in the cms.xml file are <cms_index_index> and <cms_index_defaultindex>. Let’s unravel the mystery behind these handles.

The Basics of Magento Layout Handles

Before we dive into the specifics, it’s crucial to understand the concept of layout handles in Magento. These handles act as identifiers for different areas or pages within your store where you can apply custom layout updates using XML files.

In short, <cms_index_index> and <cms_index_defaultindex> are simply two distinct layout handles used for managing the CMS index page—what most people refer to as the homepage in Magento.

The Role of <cms_index_index>

The <cms_index_index> handle is the default layout handle for the homepage. It’s primarily used to apply general changes to your store’s home page, such as adding blocks or modifying existing ones.

For instance, if you want to add a new block containing promotional content exclusively on your homepage, you would use this handle in your XML file:

<layout version="1.0">
    <cms_index_index>
        <reference name="content">
            <block type="core/text_list" after="-" name="promo_block">
                <action method="setText">
                    <text><![CDATA[Your promotional content here!]]></text>
                </action>
            </block>
        </reference>
    </cms_index_index>
</layout>

This XML code snippet adds a new text block with promotional content to the homepage, appearing after all other blocks in the content area.

The Mystery of <cms_index_defaultindex>

Now, let’s address the elephant in the room—the <cms_index_defaultindex> handle. To be honest, this handle is essentially redundant and can often cause confusion among developers.

In previous versions of Magento (1.x), there was a separate homepage layout (defaultindex.xml) that could be overridden by this handle. However, with the introduction of layouts in 2.x and beyond, Magento merged these two files into one (cms_index_index).

As a result, using <cms_index_defaultindex> will have no effect, as it is not recognized by your store’s layout system. It’s merely an artifact from earlier versions that serves no functional purpose.

Why <cms_index_defaultindex> is Now Obsolete

The main reason why the <cms_index_defaultindex> handle has become obsolete is due to Magento’s architectural changes:

  1. Layout Consolidation: In the newer versions, the default index and homepage layouts have been combined into a single file (cms.xml), making the distinction between these two handles redundant.

  2. Simplified Layout System: The layout system in more recent Magento versions focuses on a unified approach for managing all CMS pages (including the homepage) under a single handle—<cms_index_index>.

Best Practices

To avoid confusion and ensure your code remains compatible with modern Magento versions, it’s recommended to:

  1. Avoid using <cms_index_defaultindex> in your custom XML files: Stick with the standard <cms_index_index> handle for all homepage-related layout updates.

  2. Keep your layout files organized: Maintain a clean and well-structured XML hierarchy to make your customizations easier to manage and maintain over time.

  3. Stay informed about Magento’s latest developments: Keep updating your knowledge as the platform evolves to avoid working with outdated or deprecated features like the <cms_index_defaultindex> handle.

Conclusion

In summary, while both <cms_index_index> and <cms_index_defaultindex> were once used for managing Magento’s homepage layout, the latter has become obsolete in modern versions of the platform. To ensure your store remains up-to-date and performs optimally, it is essential to adopt best practices and focus on using the standard <cms_index_index> handle for all homepage-related layout customizations.

For more information about Magento XML layout files and advanced configuration techniques, check out our comprehensive guide at https://laravelcompany.com/magento-layout-files-best-practices.

Indexing Themes

Our network