Dynamic Responsive Image
Provides a field formatter that dynamically generates responsive image styles on-the-fly based on container dimensions, eliminating the need for pre-configured responsive image styles.
drimage
Install
composer require 'drupal/drimage:^2.3'
Overview
Dynamic Responsive Image (drimage) is an alternative to Drupal core's Responsive Image Style module. It takes the pain away from configuring and maintaining responsive image styles by simply not requiring any configuration. Instead of pre-defining breakpoints and image styles, drimage calculates the optimal image dimensions based on the actual container size in the browser and generates the appropriate image style dynamically.
When a page loads, JavaScript measures the container width and requests an optimally-sized image from the server. The module automatically creates and caches image styles as needed, serving perfectly-sized images for any screen size or device. This approach reduces disk space usage since only actually-needed image sizes are generated, while ensuring images always match their display context.
The module supports multiple image handling modes including simple scaling, fixed aspect ratio cropping, background images with parallax effects, and integration with Image Widget Crop for manual crop areas. It includes WebP support through both Drupal core and the ImageAPI Optimize WebP module, device pixel ratio detection for retina displays, and native browser lazy loading.
Features
- Automatically generates responsive image styles on-the-fly without manual configuration
- Supports multiple image handling modes: scale, fixed aspect ratio crop, background image, and Image Widget Crop integration
- WebP image format support via Drupal core image conversion or ImageAPI Optimize WebP module
- Device pixel ratio detection for high-DPI/retina display optimization
- Configurable threshold to limit the number of generated image styles and save disk space
- Native browser lazy loading with configurable offset for preloading images before they enter viewport
- Focal Point module integration for intelligent cropping based on focal point coordinates
- Background image mode with CSS parallax effects (fixed/scroll attachment, cover/contain sizing)
- Apache htaccess rules for serving existing image derivatives without bootstrapping Drupal
- Stage File Proxy integration for development environments
- Automatic cleanup of generated image styles when related configuration changes
- Drush command for bulk deletion of generated image styles
- Hides auto-generated image styles from the Image Styles admin listing for cleaner UI
Use Cases
Responsive Hero Images
Use the 'Fixed aspect ratio crop' mode with a wide ratio like 16:9 or 21:9 for hero banners. Drimage will generate appropriately sized versions for all screen widths while maintaining the cinematic aspect ratio. Enable device pixel ratio detection for sharp images on retina displays.
Full-Width Background Images with Parallax
Use 'Background image' mode with 'fixed' attachment for parallax scrolling effects. Set position to 'center center' and size to 'cover' for images that fill their container regardless of screen size. The image's height is controlled by CSS on the container element.
Product Gallery with Manual Crops
Use 'Image widget crop' mode with a square crop type for consistent product thumbnails. Content editors can manually position the crop area on each image, and drimage generates optimally-sized versions of that cropped area for different display contexts.
Performance Optimization for Image-Heavy Sites
Set a higher threshold value (e.g., 400-500 pixels) to reduce the number of generated image styles while accepting slightly more browser-side scaling. Enable WebP support for 25-35% smaller file sizes. Use the htaccess prepend file to serve existing derivatives without Drupal bootstrap.
Art Direction with Focal Point
Install the Focal Point module for intelligent cropping. Editors set focal points on images, and drimage ensures the important part of each image remains visible across all generated sizes, avoiding awkward crops on mobile devices.
Tips
- Enable device pixel ratio detection for crisp images on retina displays, but be aware this increases bandwidth usage for high-DPI screens
- Use the 'Cache maximum age' setting only if NOT using Apache htaccess rules - the htaccess approach is more efficient as it bypasses Drupal entirely
- The 'Background image' mode is ideal for hero sections where CSS controls the container height and the image should fill it completely
- When using Image Widget Crop, aspect ratios should be consistent across the crop type - drimage uses the crop type's aspect ratio for sizing calculations
- Install and configure the htaccess prepend file in production to dramatically reduce server load by serving existing image derivatives directly from Apache
- Run 'drush drimage:delete-styles' after making significant configuration changes to ensure all new images use the updated settings
Technical Details
Admin Pages 1
/admin/config/media/drimage
Configure global settings for dynamic responsive image generation including image style thresholds, WebP support, device pixel ratio detection, and caching behavior.
Permissions 1
Hooks 2
hook_drimage_proxy_cache_periods_alter
Allows modules to modify the available cache period options displayed on the drimage settings form.
hook_drimage_image_style_alter
Allows modules to modify auto-generated image styles before they are saved. Useful for adding additional image effects like watermarks, color adjustments, or custom crop types.
Drush Commands 1
drush drimage:delete-styles
Deletes all drimage-generated image styles from the database. Useful for cleanup or when configuration changes require regenerating all styles.
Troubleshooting 6
Check browser console for JavaScript errors. Ensure the image field is using the 'Dynamic Responsive Image' formatter. Verify the source image file exists and is accessible. Check file permissions on the styles directory.
Increase the 'Minimum difference per image style' threshold in drimage settings. A higher value (300-500 pixels) significantly reduces the number of generated styles while slightly increasing browser-side scaling.
Verify your image toolkit (GD or ImageMagick) supports WebP by checking the status report at /admin/reports/status. Ensure either core_webp or imageapi_optimize_webp is enabled in drimage settings (not both). For ImageAPI Optimize WebP, confirm a default pipeline is configured.
Configure Apache htaccess rules using the provided htaccess.prepend.txt file to serve existing derivatives directly without bootstrapping Drupal. This significantly reduces server load for repeat requests.
Drimage caches image styles aggressively. Clear caches or run 'drush drimage:delete-styles' to remove all generated styles. They will be regenerated on next request with updated crop information.
This warning is informational. Drimage bypasses the insecure derivatives protection because it uses file IDs rather than image tokens for security. The module handles security through its own mechanisms.
Security Notes 3
- Drimage bypasses Drupal's allow_insecure_derivatives protection but implements security through file ID validation and dimension checking
- The module validates requested dimensions against configured thresholds to prevent abuse through arbitrary dimension requests
- Cache headers should be configured appropriately - disable caching if using htaccess rules, or set appropriate max-age values for CDN/proxy caching