how to add grid under a tab in magento custom admin module?

how to add grid under a tab in magento custom admin module?

August 23, 2026 · Illustrated author avatarBy Stefan Bogdanescu
how to add grid under a tab in magento custom admin module?

Adding a Grid Under a Custom Tab in Magento Admin

Creating a grid under a custom tab in your Magento admin module is a common requirement for extending the admin interface. In this guide, we’ll walk you through the process of adding a grid similar to the one found under “Customers -> Wishlist”.

Creating the Module Setup File

First, ensure you have the necessary setup file for your module. If not, create it in app/code/Vendor/Module/etc named module.xml. It should look something like this:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_Module" setup_version="1.0.0"/>
</config>

Defining the Grid

Next, you’ll need to define your grid in an XML file located at app/code/Vendor/Module/etc/adminhtml/menu.xml. Here’s a basic example:

<menu xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Backend:etc/menu.xsd">
    <item name="Vendor_Module::tab" parent="Magento_Backend::system">
        <title translate="true">Tab Title</title>
        <sortTitle translate="true">Sort Order of Tab Title</sortTitle>
    </item>
</menu>

Replace Vendor_Module::tab with the identifier you want for your tab. The parent attribute determines where in the menu hierarchy to place your new tab.

Creating the Grid Block

In your module’s directory, create a file named block/adminhtml/grid/grid.php. This will be the main block for your grid.

class Grid extends \Magento\Backend\Block\Widget\Grid\Extended
{
    protected $_template = 'Vendor_Module::grid.phtml';
}

The $_template property determines which PHTML file will render the grid’s content.

Creating the Grid PHTML File

Under app/code/Vendor/Module/view/adminhtml/templates, create a new folder named “grid” and inside it, a file called grid.phtml. This is where you’ll define your grid’s layout:

<?php
$block = $this->getLayout()->createBlock('Vendor_Module\Block\Adminhtml\Grid');
echo $block->toHtml();
?>

This line creates an instance of the Grid block we defined earlier and outputs its content.

Adding the Grid

Finally, you need to add your grid to the tab. Update your module’s etc/adminhtml/routes.xml file with the following:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Adminhtml:etc/routes.xsd">
    <router id="admin">
        <route id="vendor_module" frontName="vendor_module">
            <area>
                <argument name="node" xsi:type="string">main</argument>
                <arguments>
                    <argument name="modules" xsi:type="array">
                        <item name="Vendor_Module" xsi:type="string">Vendor_Module</item>
                    </argument>
                </arguments>
            </area>
        </route>
    </router>
</config>

This maps the vendor_module route to your module, allowing you to access it from a URL like /admin/vendor_module/grid/index.

Remember to run all necessary composer commands (composer compile, php bin/magento setup:upgrade, etc.) after making these changes.

Conclusion

By following this guide, you should now be able to create a custom grid under a tab in your Magento admin module. The key is to properly define the menu item, create the grid block and template, and map the route correctly.

If you need more advanced functionality or want to explore best practices for Magento development, I highly recommend checking out Laravel Company. They offer a wealth of resources on Magento development strategies and best practices.

Extensions Admin Configuration Orders

Our network