Magento 2 - add a category attribute

Magento 2 - add a category attribute

August 26, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento 2 - add a category attribute

Magento 2: Add a Custom Category Attribute

Introduction

Creating custom category attributes in Magento 2 is a common requirement for extending the functionality of your e-commerce store. In this guide, we’ll walk through the steps to add a new attribute using the official documentation provided by Magento.

The user has shared their current implementation and expressed that it isn’t working as expected. Let’s troubleshoot their code and provide guidance on how to correctly add a custom category attribute in Magento 2.

Understanding the Core Issue

The user is following the official guide for adding a category attribute, but their implementation isn’t working. The provided code seems to be missing some key components that are necessary for Magento 2’s module system.

Analysis of the Current Code

InstallData.php

The InstallData class is correctly set up with an EAV setup factory, and the attribute creation method appears valid on first glance:

public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
{
    $eavSetup = $this->eavSetupFactory->create(['setup' => $setup]);
    $eavSetup->addAttribute(
        \Magento\Catalog\Model\Category::ENTITY,
        'disposizione',
        [
            // Attribute configuration
        ]
    );
}

category_form.xml

The form field definition for the disposizione attribute looks fine:

<field name="disposizione">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            // Field configuration
        </item>
    </argument>
</field>

module.xml

The module.xml file is also correctly defined with the setup version:

<module name="Ng_AddAttribute" setup_version="1.0.0" />

registration.php

The registration file appears to be in order as well:

\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Ng_AddAttribute',
    __DIR__
);

The Missing Pieces

After reviewing the provided code, it seems that the user has missed a critical step: registering their custom module in app/code/Ng/AddAttribute/etc/module.xml. This file is necessary for Magento to recognize and load the custom module.

The user also hasn’t created an event observer to trigger the attribute creation during module installation. In Magento 2, you need to create an event observer that listens for the setup:upgrade command and triggers the attribute addition.

The Correct Approach

Step 1: Create a Custom Module

First, ensure that you have a well-structured custom module folder:

app/code/Ng/AddAttribute
└── etc
    └── module.xml
└── registration.php
└── setup
    ├── InstallData.php
    └── upgrade_data.php
└── view
    └── frontend
        └── ui_component
            └── category_form.xml

Step 2: Register the Module in module.xml

Create a module.xml file with correct content:

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

Step 3: Create an Event Observer

Create an upgrade_data.php file in the setup folder to listen for the setup:upgrade event:

use Magento\Framework\Setup\UpgradeDataInterface;
use Magento\Framework\Setup\ModuleContextInterface;
use Magento\Framework\Setup\ModuleDataSetupInterface;

class UpgradeData implements UpgradeDataInterface
{
    private $eavSetupFactory;

    public function __construct(EavSetupFactory $eavSetupFactory)
    {
        $this->eavSetupFactory = $eavSetupFactory;
    }

    // Implement the upgrade method here
}

Step 4: Add Attribute Creation Logic

In your upgrade_data.php file, implement the attribute creation logic within the upgrade method:

public function upgrade(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
{
    if ($context->getVersion() < '1.0.0') {
        // Your attribute addition logic here
    }
}

Step 5: Execute the Setup Commands

After creating your custom module and implementing the event observer, run the following commands:

php bin/magento setup:upgrade

Conclusion

Adding a custom category attribute in Magento 2 requires careful attention to the module system’s requirements. Ensure that you have correctly registered your custom module and implemented an event observer to trigger the attribute creation during the setup:upgrade command.

For more detailed guidance on Magento 2 development, consider exploring our comprehensive resources at Laravel Company. We offer expert insights, tutorials, and best practices for working with Magento 2 effectively.

Magento 2 Catalog Extensions Configuration

Our network