Media Responsive Thumbnail
Adds a field formatter for Media reference fields that displays responsive images using Drupal's core Responsive Image module.
media_responsive_thumbnail
Install
composer require 'drupal/media_responsive_thumbnail:^2.0'
Overview
Media Responsive Thumbnail bridges the gap between Drupal's Media module and Responsive Image module by providing a specialized field formatter. This formatter enables you to display Media entity reference fields exactly like standard Image fields with the Responsive Image formatter.
The module solves a common challenge in Drupal where media reference fields cannot natively use responsive image styles. By extending the core ResponsiveImageFormatter, it brings all the responsive image capabilities to media fields, including proper srcset generation, art direction support, and resolution switching.
The formatter automatically detects the source field of the media entity and uses it for rendering. If the source field is empty, it gracefully falls back to using the media entity's thumbnail. This ensures that the formatter works reliably across different media types.
Features
- Provides a 'Responsive thumbnail' field formatter for entity reference fields targeting media entities
- Extends Drupal core's ResponsiveImageFormatter to inherit all responsive image capabilities
- Supports linking images to the parent content entity or to the media item itself
- Automatically uses the media source field for image display with fallback to thumbnail
- Properly handles cache tags from responsive image styles and individual image styles
- Supports lazy loading configuration inherited from the responsive image formatter
- Full multilingual support with proper language-aware URL generation
- Compatible with Drupal 8, 9, 10, and 11
Use Cases
Hero images with multiple breakpoints
When building a hero section that needs to display different image crops or sizes at various breakpoints, use this formatter with a responsive image style that defines appropriate image styles for mobile, tablet, and desktop. Reference your hero image through a media reference field rather than a direct image field to benefit from Media library reusability.
Article featured images
For article content types using Media library for featured images, configure the featured image display to use the Responsive thumbnail formatter. This ensures your featured images load optimally across all devices while maintaining the benefits of centralized media management.
Gallery or listing pages with responsive thumbnails
When displaying media items in a view or listing context, use this formatter to ensure thumbnails adapt to the available space. Combined with a responsive image style that includes multiple resolutions, this provides optimal loading performance on high-DPI displays.
Replacing Image fields with Media reference fields
When migrating from direct Image fields to Media reference fields to leverage the Media library, this formatter allows you to maintain the responsive image behavior that was previously available with the standard Image field's responsive formatter.
Tips
- Create responsive image styles before configuring this formatter - you need at least one responsive image style to use with this formatter
- Use the 'Linked to content' option when displaying media in article teasers to create clickable thumbnails that lead to the full article
- Enable lazy loading for images below the fold to improve page load performance
- The formatter works with any media type that has an image source field, not just the 'Image' media type
- For optimal performance, ensure your responsive image styles include appropriate image style mappings for common viewport widths
Technical Details
Troubleshooting 4
The 'Responsive thumbnail' formatter only appears for entity reference fields that specifically target media entities. Verify that your field's 'Reference type' is set to 'Media' in the field storage settings.
Ensure you have selected a valid Responsive Image Style in the formatter settings. Also verify that the media entities have valid source images uploaded and that the image styles referenced by the responsive image style exist.
The link only appears when the 'image_link' setting is configured in the formatter. Edit the display settings for your field and select either 'Linked to content' or 'Linked to media item' in the formatter configuration.
This occurs when the media entity's source field is empty. The formatter falls back to the thumbnail in this case. Ensure your media entities have their primary source field populated with an image.
Security Notes 2
- This module is covered by Drupal's security advisory policy
- The formatter properly checks entity access before rendering, ensuring that users only see media they have permission to view