Focal Point Scale

Focal Point Scale resizes images without cropping them and marks where the subject of each image is, so your theme's CSS can fit one image into any shape and keep that subject in view.

In Drupal, an image style creates a resized copy of every uploaded image. To show the same photo as a wide banner on desktop and as a square on mobile, you usually create one cropping style per shape, and the server stores a cropped file for each. The Focal Point module lets editors click the most important spot in an image, so those crops keep it in frame.

Focal Point Scale takes a different route. It only scales the image, so the whole picture is kept, and it writes the focal point onto the rendered <img> as two CSS custom properties. The browser does the framing with object-fit and object-position. One image file then serves every aspect ratio on the site, and changing a ratio is a CSS change rather than a new image style and a batch of regenerated files.

Features

• Adds a Scale and expose focal point image effect. It resizes exactly like core's Scale effect: the aspect ratio is preserved, upscaling is optional and nothing is cropped.
• Every image rendered through a style with this effect gets --focal-point-x and --focal-point-y as percentages, plus a focal-point-image class for your CSS:
  

  <img class="focal-point-image"
       style="--focal-point-x:37.5%;--focal-point-y:22%" …>

• Works wherever Drupal renders an image style: image field formatters, Views image fields, media thumbnails and custom render arrays. Responsive images from core's Responsive Image module work too.
• Uses the focal points editors already set with Focal Point. When an image has none, it falls back to Focal Point's configured default.
• Keeps two decimals (37.5%, not 38%), where Focal Point's own conversion rounds to whole numbers.
• Cache-aware: when an editor moves a focal point, pages showing that image are refreshed.
• Each effect can set its own custom property prefix (for example --hero), and the class can be switched off.
• Adds a status report check that warns when a style combines this effect with cropping or rotating, or when a responsive image style mixes them. Those setups put the focal point in the wrong place.
• Ships no CSS or JavaScript, so your theme decides how images are fitted.
• For developers, a resolver service (focal_point_scale.resolver) returns any image's focal point as percentages.

When to use it

• Hero banners that change shape between breakpoints, for example 21:9 on desktop and 4:5 on mobile.
• Card grids and teasers where the same image appears in several ratios.
• Sites with many cropping image styles that want fewer styles and fewer derivative files on disk.
• Front-end teams that prefer to handle framing in CSS, next to the rest of the layout.

When not to use it: when you need an actual cropped file, for example a fixed-size image for social sharing (og:image), email or RSS, where no CSS is applied. Use Focal Point's own crop effects for those styles. Both can be used on the same site.

Post-Installation

The module has no settings page of its own. Everything is set up on the image styles you create.

1. Check Focal Point. At Configuration » Media » Focal Point (/admin/config/media/focal-point), check the default focal point (50,50 is the center). On your image field's Manage form display, set the widget to Image (Focal Point) so editors can set the point.
2. Create an image style. At Configuration » Media » Image styles (/admin/config/media/image-styles), add a style and add the Scale and expose focal point effect. Set a maximum width, leave the height empty and leave upscaling off. Don't add a crop effect to the same style.
3. Use the style. On the image field's Manage display (or the media type's), choose the Image formatter with your new style. For responsive images, add the effect to the image styles your responsive image style uses, at least its fallback style.
4. Add CSS to your theme. For example:
   

   .focal-point-frame {
     position: relative;
     overflow: hidden;
     aspect-ratio: 16 / 9;
   }
   .focal-point-frame > .focal-point-image,
   .focal-point-frame > picture {
     position: absolute;
     inset: 0;
     display: block;
   }
   .focal-point-image {
     width: 100%;
     height: 100%;
     object-fit: cover;
     object-position: var(--focal-point-x, 50%) var(--focal-point-y, 50%);
   }

   Wrap the image field in an element with the focal-point-frame class, and change aspect-ratio per breakpoint as needed.

5. Check the status report. Reports » Status report shows a Focal point scale line that flags any style mixing this effect with cropping.

Things to keep in mind

• object-position only has an effect together with object-fit. An image shown at its natural ratio doesn't move, which is correct.
• The focal point is written in a style attribute. A Content-Security-Policy without style-src 'unsafe-inline' (or a matching nonce or hash) strips it, and images fall back to centered framing.
• A <picture> element has only one <img>, so every image style in a responsive mapping must keep the original aspect ratio.
• Existing image styles are not changed. Only styles you add the effect to are affected.

Additional Requirements

• Drupal 11.2 or newer.
• Focal Point 2.1 or newer, and its dependency Crop API.
• Core's Image module.
• A theme you can add CSS to.

Recommended modules/libraries

• Responsive Image (Drupal core): serve different file sizes per breakpoint while keeping a single focal point.
• Media (Drupal core): Focal Point works on media image fields, so editors set the point once per media item and it applies wherever that item is reused.

Similar projects

• Focal Point: its Focal Point Scale and Crop effect crops on the server, which means one image style and one stored file per aspect ratio. Focal Point Scale reuses Focal Point's widget and data but leaves the cropping to CSS. The two complement each other.
• Image Widget Crop: editors draw a crop area for each ratio by hand. It gives full control per ratio, but needs more editorial work and more image styles.

Community Documentation

• README: full configuration, theming and troubleshooting notes.

AI disclosure

Most of this module's code, tests and documentation were written with an AI coding assistant. The maintainer set the design, reviewed the output, and checks every change against Drupal's coding standards and the project's automated tests before it is committed.

Even so, AI-written code can contain mistakes that a review misses. If something behaves unexpectedly, please open an issue. Bug reports and patches are very welcome.