Focal Point
Allows users to specify the focal point of an image for use during cropping, ensuring important parts of images are not cropped out.
focal_point
Install
composer require 'drupal/focal_point:^2.1'
Overview
Focal Point allows you to specify the portion of an image that is most important. This information can be used when the image is cropped or cropped and scaled so that you don't, for example, end up with an image that cuts off the subject's head.
The module works by defining the focus as a single point on the image, represented as X and Y coordinates in percentages (e.g., "50,50" for the center). This focal point data is stored using the Crop API module and is then used by image effects to ensure the focal point remains as close to the center of the cropped image as possible.
The module provides a visual interface with a draggable crosshair indicator that allows content editors to easily set the focal point on uploaded images. A preview feature is available to see how the image will look with different image styles applied.
Features
- Interactive focal point selector with a draggable crosshair indicator on image previews
- Three image effects: Focal Point Crop, Focal Point Scale and Crop, and Focal Point Crop by Width
- Real-time preview page showing how images will be cropped across all image styles using focal point effects
- Full integration with Drupal's Media Library module for setting focal points on media entity images
- Migration support from Drupal 7 focal point data to Drupal 9/10/11 crop entities
- CSRF token-protected preview access for unsaved content
- Keyboard accessible focal point field (double-click crosshair to reveal coordinates)
- Click-to-set focal point on preview images
- Configurable default focal point value per field widget instance
- Support for IMCE file browser integration
Use Cases
Portrait Photography
When displaying portrait photos across different image styles (hero banners, thumbnails, cards), set the focal point on the subject's face. This ensures that regardless of the crop dimensions, the person's face remains visible and centered rather than being cut off at the top of the frame.
Product Images with Key Details
For e-commerce product images where a specific feature needs to be highlighted (like a logo, button, or unique design element), place the focal point on that feature. When the image is displayed in various contexts (product listing, detail page, cart preview), the important detail remains visible.
Responsive Hero Images
For hero banners that display differently on desktop (wide) vs mobile (narrow/square), setting the focal point ensures the main subject of the photo is preserved in both views. The module handles the different crop ratios automatically.
Event Photography
For event photos where the main action or speaker needs to be highlighted, the focal point ensures that cropped thumbnails and previews always show the most important moment rather than arbitrary crops from the center.
Magazine-Style Layouts
When implementing designs with mixed image aspect ratios (feature images, sidebars, article grids), focal point ensures consistent quality across all placements without requiring editors to upload multiple cropped versions of each image.
Tips
- Double-click the focal point crosshair indicator to reveal the exact coordinate values in the text field for precise adjustments
- You can click anywhere on the preview image to immediately move the focal point to that location
- Use the Preview link to see how your image will appear across all focal point-enabled image styles before saving
- For multi-value image fields, each image can have its own independent focal point
- The default focal point (50,50) represents the exact center of the image - only change it if the subject is off-center
- When choosing a preview image style for the widget, avoid styles that crop or change aspect ratio as this affects focal point accuracy
- Focal points are stored as percentages, so they remain accurate even if the original image dimensions change
Technical Details
Admin Pages 1
/admin/focal_point/preview/{fid}/{focal_point_value}
Displays a preview of the original image along with all derivative images generated by image styles that use focal point effects. This allows content editors to see exactly how their images will be cropped before saving content. The preview opens in a modal dialog and shows thumbnails of each image style that can be clicked to view larger versions.
Hooks 5
hook_entity_insert
Saves focal point values for image fields when entities are created
hook_entity_update
Saves focal point values for image fields when entities are updated
hook_theme
Defines the focal_point_preview_page theme hook for the preview page template
hook_imce_supported_widgets_alter
Adds the focal point widget to IMCE's supported widgets list for file browser integration
hook_form_FORM_ID_alter (media_library_add_form_upload)
Modifies the Media Library upload form to integrate focal point functionality
Troubleshooting 5
You must have at least one image style defined that uses a focal point effect (Focal Point Crop, Focal Point Scale and Crop, or Focal Point Crop by Width). Navigate to /admin/config/media/image-styles and add focal point effects to your image styles.
Ensure the widget is configured with a preview image style that does NOT use focal point effects and does NOT alter the aspect ratio of the original image. The thumbnail style works well as a default.
Derivative images are cached. After changing a focal point, the old cached images need to be flushed. The preview page automatically flushes the cache, but for production images you may need to clear the image style cache or use image_path_flush().
Ensure the image field is configured to use the 'Image (Focal Point)' widget under Manage form display. The focal point is only saved when using this specific widget.
For Media entities, you must configure the Media type's source field (typically the Image field on the Image media type) to use the 'Image (Focal Point)' widget. Navigate to Structure > Media types > Image > Manage form display and update the Image field widget.
Security Notes 2
- The preview page uses CSRF token validation to prevent unauthorized access to image previews for unsaved content
- File access on the preview page is restricted to users who have permission to edit entities that reference the file, or who provide a valid preview token