When customizing Magento 2, it’s often necessary to display images in the admin grids, especially for product-related data. In this blog post, we will walk through how to add a custom image thumbnail column to your admin grid. This guide is structured to help developers working with Magento 2.4.x and PHP 8.0+.

Prerequisites

Before you begin, ensure that you have:

Step 1: Extend the Admin Grid

Let’s assume you have a custom grid or are extending an existing one (e.g., for products). You will need to modify the grid to include an image thumbnail.

First, locate or create the Grid.php file, which is the backend model for your grid. This file is typically located in app/code/Vendor/Grid/Ui/Component/Listing/Column.

Add a new column to your grid:

<?php

declare(strict_types=1);

namespace Vendor\Grid\Ui\Component\Listing\Column;

use Magento\Framework\Exception\NoSuchEntityException;
use Magento\Ui\Component\Listing\Columns\Column;
use Magento\Framework\View\Element\UiComponent\ContextInterface;
use Magento\Framework\View\Element\UiComponentFactory;
use Magento\Store\Model\StoreManagerInterface;
use Magento\Framework\UrlInterface;

class Thumbnail extends Column
{
    /**
     * The name of the column
     */
    const string NAME = 'thumbnail';

    /**
     * The alt field of the image
     */
    const string ALT_FIELD = 'Image';

    /**
     * @param ContextInterface $context
     * @param UiComponentFactory $uiComponentFactory
     * @param StoreManagerInterface $storeManager
     * @param array $components
     * @param array $data
     */
    public function __construct(
        ContextInterface $context,
        UiComponentFactory $uiComponentFactory,
        private readonly StoreManagerInterface $storeManager,
        array $components = [],
        array $data = []
    ) {
        parent::__construct($context, $uiComponentFactory, $components, $data);
    }

    /**
     * Prepares the data source for the thumbnail column
     *
     * @param array $dataSource
     * @return array
     * @throws NoSuchEntityException
     */
    public function prepareDataSource(array $dataSource): array
    {
        if (isset($dataSource['data']['items'])) {
            $fieldName = $this->getData('name');
            foreach ($dataSource['data']['items'] as & $item) {
                $filename = $item[$fieldName];
                $item[$fieldName . '_src'] = $this->getImage($filename);
                $item[$fieldName . '_alt'] = $this->getAlt($item) ?: $filename;
                $item[$fieldName . '_orig_src'] = $this->getImage($filename);
            }
        }

        return $dataSource;
    }

    /**
     * Returns the full URL of the image
     *
     * @param string $imagePath
     * @return string
     * @throws NoSuchEntityException
     */
    public function getImage(string $imagePath): string
    {
        if ($imagePath != "") {
            return $this->storeManager->getStore()->getBaseUrl(
                UrlInterface::URL_TYPE_MEDIA) . '/image/' . $imagePath;
        }
        return "";
    }

    /**
     * Returns the alt text for the image
     *
     * @param array $row
     * @return string|null
     */
    protected function getAlt(array $row): ?string
    {
        $altField = $this->getData('config/altField') ?: self::ALT_FIELD;
        return $row[$altField] ?? null;
    }
}

Step 2: Modify the ui_component XML

Next, modify or create your ui_component file (usually found in app/code/Vendor/Grid/view/adminhtml/ui_component/vendor_grid_post_listing.xml). Add a new column entry for the thumbnail:

<column name="image" class="Vendor\Grid\Ui\Component\Listing\Column\Thumbnail">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            <item name="component" xsi:type="string">Magento_Ui/js/grid/columns/thumbnail</item>
            <item name="sortable" xsi:type="boolean">false</item>
            <item name="altField" xsi:type="string">name</item>
            <item name="has_preview" xsi:type="string">1</item>
            <item name="label" xsi:type="string" translate="true">Image</item>
        </item>
    </argument>
</column>

Step 3: Test the Grid

Now that you’ve added the thumbnail column, it’s time to test. Run the following commands to clear cache and reindex:

php bin/magento cache:flush
php bin/magento indexer:reindex

Head over to the Magento Admin Panel, and navigate to your grid. You should now see image thumbnails displayed in the grid.

admin-grid-thumbnail

Step 4: Handling Image Paths Dynamically

In the code above, we’ve assumed the image path is located in pub/media/image. Depending on your setup, you might need to modify the image path based on your specific needs.

For example, if the image is stored in a custom folder, simply change the image path construction in the prepareDataSource method.

Conclusion

Displaying an image thumbnail in the Magento 2 Admin Grid is an effective way to improve the admin’s user experience, especially when managing products. With this guide, you’ve learned how to add a thumbnail column to any grid, and the steps are flexible enough for a wide range of customizations.