How do I find out which handles should I use when I want to customize a certain page?

For example, by searching online, I found out that checkout_onepage_index is the handle to modify the Checkout page. I don't know about this magic, but somehow somebody just know it and I want to know how the learn this magic.

<?xml version="1.0"?>
        <reference name="head"></reference>

How do I know what handles if let say I want to modify the success page instead? or the frontend order detail page? etc...?

5 Answers 5


You can add this to your controller action. It will show handles in more neat way than var_dump. Strange that this answer is not already on stack.


In the simplest case, layout handles represent frontName_controller_action.

So, in your example:

  • frontName is checkout for the Mage_Checkout module (as defined by its config.xml file in the <routers></routers> section).
  • controller is onepage for Mage_Checkout_OnepageController.
  • action is index for Mage_Checkout_OnepageController::indexAction()

Note that this is only the simplest case. Layout handles can be created/added in many other places and ways, such as the catalog logic (PRODUCT_TYPE_x layout handles for different product types).

A good way of finding layout handles to use is to check the files in design/frontend/base/default/layout - this directory stores all of the layout files of the base package/theme, and it has most (if not all) of the out of the box layout handles that you can utilize.

  • is frontName_controller_action just a conventions? I believed there are some handles which does not follow these pattern, is it true?
    – Yeo
    May 30, 2015 at 7:15
  • Yup, that's just a convention for most controllers. And, yes, there are plenty of other layout handles, and you can even add your own.
    – Agop
    May 30, 2015 at 17:03

We wrote down, how the handle is built (and many other things) here:


and we wrote down a few layout handles which one should know, like customer_logged_in|out

##Custom Action

Layout handle will be build with the NODE name!


Route: frontend// Layout Handle: companyModule_frontend_controllerName_actionName

Magento uses only parts of the Layout-XML file, depending on the requested page. These parts are called layout handle. There are a few which are used every time, and others which are belonging to exactly one URL

The most important Layout-Handles which don't belong to a page:

  • (all pages)
  • <customer_logged_(in|out)> (customer status)
  • <catalog_category_default> (category w/o LN)
  • <catalog_category_layered> (category with LN)
  • <catalog_category_view> (all categories)
  • <catalog_product_view> (product detail page)

Special Layout-Handle


Custom Layout handle

Easiest: add one with an observer

public function addMyOwnLayoutHandle(){

than you can use in layout XML


The convention is made this way because before loading the layout magento first search for the handle with this type of handle,so that it can find the template from the controller.But you can make your own custom handles

public function controllerActionLayoutLoadBefore(Varien_Event_Observer $observer) { /** @var $layout Mage_Core_Model_Layout */ $layout = $observer->getEvent()->getLayout();

        $id = Mage::app()->getRequest()->getParam('id');

        /* or */

        if($ourCoolObject = Mage::registry('our_cool_object'))
            $id = $ourCoolObject->getId();


By the way there are 5 type of handles briefed below and we are talking about the fourth one here.


For more info refer



Magento 2

Quick way to do it is

  1. Go to page in question
  2. Go to page inspector tool in your browser
  3. Check class names on body tag. One of them is going to be the name of a corresponding layout handle.

Remember, body tag class names will typically contain dashes ' - ' as word separators, while the layout handle name you are searching for will have lower dashes ' _ ' instead. So make sure to replace ' - ' with ' _ ' during file search.


Home page Magento 2 based home page. Showing classes on body tag in browser inspector tool

Cart page Magento 2 based cart page. Showing classes on body tag in browser inspector tool

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.