Image Scale and Fill Background Effect

Image Scale and Fill Background is a Drupal image effect that scales images to fit within defined dimensions while seamlessly filling the remaining space with a background style.

It was built for The Drop Times, a Drupal news publication with several display modes at different aspect ratios. The photographs and logos that fill them arrive from contributors, press offices and event organizers worldwide, at whatever proportions the sender chose, and the editorial team was cropping or re-editing images by hand to make them fit. The approach was proposed by Sebin A. Jacob, its editor-in-chief, and has been in production there since 2024.

Features

The effect applies wherever a layout requires images of one fixed size, the sources arrive at proportions the site does not control, and cropping is not acceptable. Every derivative comes out at the configured dimensions, with nothing removed from the image.

• Scale to fit: dynamically scales the original image to fit within a specified width and height.
• Background fill: fills the excess space with
  • a tiled copy of the image, blurred or under a colored overlay;
  • a scaled copy of the image, blurred or under a colored overlay;
  • the dominant color of the image, as a single color or as a gradient.
• Transparent sources: logos and other artwork with a transparent background are given a plain filled background instead of being composited onto black. Choose a fixed color, a light or dark fill selected per image, or a tint taken from the image itself.
• Customizable options: blur intensity and spread, overlay transparency, gradient direction, and resize ratio.

Requirements

• Drupal 10.3 or later.
• The GD image toolkit that ships with Drupal. This module does not support ImageMagick or any other toolkit: on those the effect is skipped and an error is logged, and the image style produces the unmodified original.

Installation

composer require drupal/image_scale_fill

Enable the module, then add the Scale and fill background effect to an image style at /admin/config/media/image-styles. Place it last in the style: anything after it operates on the canvas this effect has drawn.

Post-Installation

The effect form shows only the settings that apply to the background type you choose.

• Width and Height: the target area the image is scaled to fit. Up to 10000 pixels per side, and no more than 40 megapixels in total.
• Background type: Tiled, Scaled, or Dominant color.
• Background style: for a tiled or scaled background, Blurred or Colored overlay. For a dominant color background, Single color or Gradient.
• Images with a transparent background: Do nothing, fill with a light or dark color to suit the image, fill with a fixed color, or fill with a pale tint or dark shade taken from the image itself. This setting replaces the background type for sources that are transparent; images without transparency are unaffected, so one image style can serve a feed of photographs and logos together. The color settings that apply to the value you choose appear with it.
• Blur radius (1 to 50) and Blur sigma (0.1 to 50, and never larger than the radius): the intensity and spread of the blur. Larger values take longer to process.
• Resize ratio (0.1 to 1): how far the background is downscaled before it is blurred. Smaller values are faster.
• Overlay transparency (0 to 100): 0 is fully transparent, 100 fully opaque. Applies to the colored overlay style.
• Gradient direction: vertical or horizontal. Applies to the gradient style.

Upgrading from 1.0.x

Run drush updatedb. Image styles that already use the effect are set to Do nothing, so the images they produce do not change. Effects added afterwards default to filling with a light or dark color. A site adopts the new behavior one style at a time.

Documentation and demonstration

Every option is documented and demonstrated with real derivatives, alongside exported image styles ready to import, at imagescalefill.zyxware.com.

Similar projects

Image Effects is the best-in-class module for image effects and offers a wide variety of them. This module does one thing it does not, and contributing the effect to Image Effects one day would be a good outcome.