Image Widget Crop
Provides an interface for using the Crop API with image fields, enabling users to define multiple crop zones per image for different crop types.
image_widget_crop
Install
composer require 'drupal/image_widget_crop:^3.0'
composer require 'drupal/image_widget_crop:8.x-2.4'
Overview
Image Widget Crop provides a user experience for applying crops to image fields using the Crop API. The module integrates with Drupal's image system to allow editors to define optimal crop zones for each image based on different crop types (aspect ratios).
The module is particularly useful for editorial sites or media management systems where the same image needs to be displayed in different contexts with different aspect ratios. For example, an article might need a wide hero image, a square thumbnail, and a vertical sidebar image - all from the same source file.
Key capabilities include: multiple crop type support per image, real-time visual cropping interface using the Cropper.js library, aspect ratio enforcement, hard and soft limit validation, required crop type validation, and integration with File Entity, Entity Browser, IMCE, and other media management modules.
Features
- Multiple crop types per image with support for different aspect ratios
- Visual cropping interface using Cropper.js library with real-time preview
- Automatic aspect ratio enforcement based on crop type configuration
- Hard and soft limit validation for minimum crop dimensions
- Required crop type validation to ensure editors define necessary crops
- Integration with File Entity for cropping images directly from file edit forms
- Support for Entity Browser, IMCE, and FileField Sources modules
- Flexible library loading: local files, Libraries API, or CDN fallback
- Notifications system for crop apply and update operations
- Warning system when images are used in multiple places
- Form API element (image_crop) for custom form integration
- Vertical tabs interface for managing multiple crop types
Use Cases
Editorial site with multiple image placements
For a news site where articles appear on homepage (wide banner), category pages (medium square), sidebar (small vertical), and article page (full width). Create crop types for each ratio (16:9, 1:1, 3:4, etc.), configure image styles with Manual crop effect, and editors can define optimal crop zones for each placement when uploading images.
E-commerce product images
Product images need consistent cropping for catalog grids, product detail pages, and zoom views. Configure crop types for each display context and require the catalog crop type to ensure all products have properly cropped thumbnails.
Media library with reusable assets
Using Media module with file entities, editors can crop images once in the media library and reuse them across content. The warn_multiple_usages option alerts editors when changing crops that affect multiple content items.
Custom form with cropping
Add cropping to custom forms using the image_crop Form API element. Load file entity, configure crop types and preview style, and process crops via image_widget_crop.manager service on form submission.
Responsive images with art direction
Combine with Responsive Image module for art-directed responsive images. Different crop types allow defining optimal focus points for various viewport sizes, ensuring important content is visible at all breakpoints.
Tips
- Use image styles with Scale (not Scale and Crop) for the crop preview to maintain aspect ratio and see the full image
- Set appropriate hard limits on crop types to ensure minimum image quality for each use case
- Enable 'Warn user when a file have multiple usages' for media libraries where files may be reused
- Use the image_widget_crop_examples submodule to test functionality before configuring production fields
- The CDN fallback works without additional setup - no library installation required for basic usage
- Configure different crop types per field based on where that field's images will be displayed
Technical Details
Admin Pages 1
/admin/config/media/crop-widget
Configure global settings for the Image Widget Crop module including Cropper library source, default crop preview style, available crop types, and notification preferences.
Hooks 7
hook_entity_insert
Automatically processes crop data when entities with image fields are created
hook_entity_update
Automatically processes crop data when entities with image fields are updated
hook_form_file_form_alter
Adds the image_crop element to file entity edit forms for image files
hook_library_info_alter
Dynamically configures the Cropper library source based on module settings (custom URL, Libraries API, or CDN)
hook_libraries_info
Defines the Cropper library for the Libraries API module integration
hook_filefield_sources_widgets
Registers the image_widget_crop widget for FileField Sources module compatibility
hook_imce_supported_widgets_alter
Adds image_widget_crop to the list of widgets supported by IMCE module
Troubleshooting 5
Crop types only appear if at least one Image Style uses them with the 'Manual crop' effect. Go to /admin/config/media/image-styles, edit or create a style, and add the 'Manual crop' effect selecting your crop type.
Check the configuration at /admin/config/media/crop-widget. Verify custom URLs are accessible, or ensure Libraries module is enabled with cropper in /libraries/cropper/dist/. The module falls back to CDN if no local library is found.
Ensure the image field widget is set to 'ImageWidget crop' in form display settings. Verify crop types are selected in the widget configuration. Check that the entity has hook_entity_insert/update being triggered.
The crop area is smaller than the crop type's hard limit minimum dimensions. Either crop a larger area or reduce the hard limit values in the crop type configuration at /admin/config/media/crop.
Enable 'Warn user when a file have multiple usages' in widget settings. When using media entities, each media item should reference unique files to avoid shared crops.
Security Notes 3
- Module relies on existing Drupal permissions - 'administer site configuration' for settings page
- Crop data is stored per-file, so users with file access can affect crops for content they don't own if files are shared
- Consider file ownership and access patterns when using shared media libraries