How to Display Category Product Position in list.phtml on Magento 2

Display Category Product Position in list.phtml on Magento 2

 

In Magento 2, the category product position refers to the numerical sort order assigned to each product when it is linked to a category. This position is stored in the catalog_category_product database table and determines the order in which products appear in category listing pages. If you want to display this position directly in your list.phtml template, you need to access the product’s position value from the category-product relationship.

This guide explains step-by-step how to fetch and render that value within your Magento 2 frontend theme.

How Magento 2 Stores Category Product Position

The product position in a category is managed as part of the category-product relationship. In the database, it is stored in the position column of the catalog_category_product table. Magento uses this value internally when sorting products by their default order.

Key points:

• The position value is unique per category and product pair.
• It can be changed from the Magento Admin under Catalog > Categories.
• Products with lower position numbers appear first when using the “Default” sort order.

Magento’s product collection already contains this data if the collection is loaded in a category context, but you need to retrieve it explicitly in list.phtml to display it.

Locating and Editing list.phtml

The list.phtml template file is typically located in:

• vendor/magento/module-catalog/view/frontend/templates/product/list.phtml (core)
• Your custom theme override: app/design/frontend/Vendor/theme/Magento_Catalog/templates/product/list.phtml

Best practice is to avoid editing core files directly. Instead, copy list.phtml into your theme’s Magento_Catalog/templates/product directory and modify it there.

Fetching the Product Position in list.phtml

To get the category product position, you can use the getCategory() method from the product’s type instance or via the layer’s current category. Here’s an example code snippet to add in list.phtml inside your product loop:

<?php
/** @var \Magento\Catalog\Model\Product $product */
$currentCategory = $block->getLayer()->getCurrentCategory();
$position = $currentCategory->getProductCollection()->getItemById($product->getId())->getData('cat_index_position');
?>

<div class="product-position">
    Position: <?= $position ?>
</div>

Explanation:

• $block->getLayer()->getCurrentCategory() fetches the category currently being viewed.
• getProductCollection() retrieves the loaded product collection for that category.
• getItemById() matches the product in the collection and fetches its cat_index_position value, which Magento internally uses for the product’s position.

Alternative Method: Using Registry or Product Extension Attributes

In some cases, especially when the product collection is filtered or modified, the cat_index_position value might not be directly available. You can instead use Magento’s Registry or add a custom extension attribute:

<?php
$currentCategory = $block->getRegistry()->registry('current_category');
$productId = $product->getId();
$position = $currentCategory->getProductsPosition()[$productId] ?? null;
?>

<div class="product-position">
    Position: <?= $position ? $position : 'N/A' ?>
</div>

This approach pulls the raw products_position array from the current category object, which maps product IDs to their position numbers.

Comparison of Methods

Method	Pros	Cons	Best Use Case
Product Collection with cat_index_position	Simple, uses existing collection data	Might not work if collection is altered	Default category product list
Registry getProductsPosition()	Direct mapping from category object	Requires category context	When collection is modified or custom-loaded
Extension Attribute	Customizable, reusable	Requires backend setup	Advanced custom modules

Styling the Position Display

Once the position is displayed in list.phtml, you can style it with CSS:

.product-position {
    font-size: 14px;
    color: #555;
    margin-top: 5px;
}

Consider showing the position only for admin or logged-in users if it’s meant for internal use, by adding a customer session check in your template.

Best Practices and Performance Considerations

• Avoid Direct DB Queries: Always use Magento’s collection or model methods instead of raw SQL for better compatibility.
• Use Theme Overrides: Never edit core list.phtml directly — always copy to your theme.
• Cache Awareness: Magento caches category product collections, so flush cache when testing changes.
• Minimize Loops: If fetching additional product data, do it in bulk rather than per-item loops.

Following these best practices ensures your customization remains upgrade-safe and performant.

Conclusion

Displaying the category product position in list.phtml on Magento 2 is straightforward when you know where to fetch it from. By using the current category’s product collection or the registry’s product position mapping, you can easily show this data alongside each product in your category listings. Always remember to follow Magento’s coding and theming best practices to maintain compatibility and performance across updates.