Simple (Image) Crop is a lightweight, mobile-friendly image cropping field for Drupal. It allows content editors to visually select a fixed-aspect-ratio crop and automatically generates an image at the exact dimensions configured for the field.
Designed for simplicity, performance, and ease of use, Simple Crop provides a complete image cropping workflow without requiring Crop API, Focal Point, or additional contributed modules.
Unlike traditional image cropping solutions, Simple Crop saves the processed image as the field's primary managed file while preserving the original uploaded image for future editing.
Features
- Dedicated image field type: Works with Drupal content entities that support configurable fields, including nodes and other entity types.
- Fixed aspect ratios: Configure an exact aspect ratio for each field, ensuring consistent image proportions across your website.
- Custom output dimensions: Define the final width and height in pixels, such as 390×280, 800×600, or 1920×1080.
- Interactive visual cropping: Move and resize the crop region directly over the uploaded image.
- Touch-friendly interface: Supports pointer-based dragging, corner resizing, pinch-to-resize gestures, and keyboard controls.
- Mobile scrolling navigation: A dedicated right-hand scrolling strip allows mobile users to navigate past the cropping interface without accidentally changing the selected crop.
- Accessible controls: Includes crop adjustment buttons, keyboard navigation, and a Done cropping / Edit crop toggle.
- Drupal AJAX integration: Designed to reinitialize the cropping interface after image uploads, removal, replacement, and AJAX-driven form updates.
- Non-destructive editing:(Optionally) preserves the original uploaded image, allowing editors to return later and select a different crop.
- Actual cropped file storage: Generates a separate Drupal-managed image containing the selected crop, resized to the configured output dimensions.
- Configurable file directories: Uses the field's File directory setting, including Drupal's supported directory tokens and public/private file storage.
- Readable filenames: Generated filenames include the original image name, crop coordinates, output dimensions, and a short collision-resistant fingerprint.
- Stored crop coordinates: Records the crop rectangle in original-image pixels, alongside references to the processed image and original source.
- Multiple field instances: Each Simple Crop field can have its own aspect ratio, output dimensions, and storage configuration.
- No external cropper dependency: Uses a lightweight JavaScript implementation without requiring Crop API, Focal Point, Hook Event Dispatcher, or third-party cropping libraries.
Image Processing and Storage
Simple Crop processes images using Drupal's configured image toolkit.
When an editor saves content, the module:
- Reads the selected crop coordinates relative to the original uploaded image.
- Validates the crop against the configured aspect ratio.
- Crops the original image to the selected region.
- Resizes the cropped region to the field's configured output dimensions.
- Saves the resulting image as a separate Drupal-managed file.
- References the processed image as the field's primary file while retaining the original source for future editing.
The original uploaded file is never overwritten during cropping.
Configurable File Storage
Simple Crop respects the File directory setting configured for each field.
The default directory for new fields is:
simple_crop/[date:custom:Y]
For example, images uploaded in 2026 can be stored under:
public://simple_crop/2026/
The directory is configurable and supports Drupal's standard directory token processing. Private file storage is also supported when configured for the field.
Readable cropped filenames help identify the original image, selected crop region, and final output size.
Example:
mcdaddy-x120_y80-x1152_y821-390x280-6fa53bc1a0.jpg
Filename components include:
- Original uploaded filename
- Top-left crop coordinates (X1, Y1)
- Bottom-right crop boundary (X2, Y2)
- Final output width and height
- Short fingerprint to prevent naming collisions
- Image file extension
Crop coordinates are measured in pixels relative to the original image, not the browser's scaled preview.
Mobile and Desktop Editing
Simple Crop includes a responsive cropping interface designed for modern mobile and desktop browsers.
On mobile devices, editors can move and resize the selected crop using touch gestures. A dedicated scrolling area on the right side of the image allows vertical navigation without interfering with cropping gestures.
The Done cropping control temporarily disables crop interaction, allowing normal scrolling over the image. Editors can reactivate cropping whenever necessary.
Primary browser testing targets include:
- Google Chrome on Android, including Samsung Galaxy devices
- Google Chrome on modern Linux desktops
- Mozilla Firefox on modern Linux desktops
The interface is designed to integrate with Drupal administration themes, including Gin and Claro. Cross-browser and cross-theme testing remains ongoing.
Post-Installation
After installing and enabling Simple Crop:
- Navigate to Manage fields for your content type or supported entity type.
- Add a new field of type Simple Crop image.
- Configure the required aspect ratio, such as 39:28 or 4:3.
- Specify the final output dimensions, such as 390×280 pixels. The dimensions must match the configured aspect ratio.
- Configure the allowed file extensions, upload destination, and File directory as required.
- Under Manage form display, select the Simple Crop (touch-friendly) widget.
- Under Manage display, select the Simple Crop image (processed) formatter.
- Create or edit content, upload an image, and visually select the desired crop.
- Save the content. Simple Crop automatically generates and stores the cropped image at the configured dimensions.
When the content is edited again, Simple Crop uses the preserved original image so that a different crop can be selected without progressively reducing image quality.
Requirements and Compatibility
- Drupal: Drupal 11.4 or later within the Drupal 11 release series, or Drupal 12.
- PHP: PHP 8.3 or later, subject to the minimum PHP requirements of the installed Drupal core version.
- Drupal core modules: Field, File, and Image.
- Image processing: GD or another Drupal-compatible image toolkit capable of processing the selected image formats.
Simple Crop does not support Drupal 10 or Drupal 11.0 through 11.3.
The module is also intended for Drupal CMS installations running a compatible Drupal core version.
No additional contributed modules are required.
Supported Image Formats
Simple Crop supports common raster image formats, including:
- JPEG / JPG
- PNG
- GIF
- WebP
Additional formats such as AVIF and BMP depend on support provided by the configured Drupal image toolkit.
Animated images may lose animation during processing, depending on the image format and toolkit.
Automated Testing
Simple Crop includes automated tests covering important parts of the cropping and image-processing workflow.
- JavaScript crop geometry and aspect-ratio calculations
- Crop movement, resizing, and coordinate validation
- JavaScript widget initialization and lifecycle handling
- PHP image processing and filename generation
- Drupal field storage and managed-file references
- Original image preservation and re-cropping behavior
- Configurable file directories and token expansion
- Functional JavaScript tests for uploading, removing, and replacing images
The source repository also includes GitLab CI configuration. Drupal integration and browser compatibility testing are ongoing.
Recommended Modules and Libraries
Simple Crop uses Drupal core functionality for file handling and image processing. No additional contributed modules or JavaScript cropping libraries are necessary.
For more advanced image transformations, the following project may be useful:
- Image Effects — provides additional image effects and processing capabilities for Drupal image styles.
Similar Projects
- Image Widget Crop — provides cropping capabilities through integration with Crop API. Particularly useful when reusable crop entities or multiple crop styles are required.
- Focal Point — allows editors to select an image's focal point for use with responsive image styles and automated cropping.
How Simple Crop differs:
- Provides a dedicated image field with cropping built directly into the editing workflow.
- Does not require separate crop entities or Crop API.
- Produces an actual resized and cropped managed file rather than relying exclusively on image styles.
- Preserves the original image for subsequent editing.
- Stores crop coordinates and image references with each field item.
- Supports configurable output dimensions and storage directories for each field.
- Prioritizes ease of use, mobile interaction, and consistent image output.
Development Notes
Simple Crop is under active development. Additional testing is particularly welcome for mobile touch interaction, Drupal AJAX form updates, supported administration themes, and newer Drupal core releases.
Previously generated derivatives are not yet automatically garbage-collected when crops are changed. Full revision and translation lifecycle cleanup remains an area for further development.
Bug reports, feature requests, testing feedback, and patches are welcome through the project's issue queue.
Supporting This Module
If you'd like to support the development of Simple Crop, contribute testing feedback, report issues, or submit improvements through the Drupal.org issue queue.
You can also contact Joseph Olstad.
Community Documentation
Project information
- Project categories: Content editing experience, Media
3 sites report using this module- Created by joseph.olstad on , updated
Stable releases for this project are covered by the security advisory policy.
Look for the shield icon below.
