Our image cropping tool takes full advantage of the Cropper.js javascript plugin as our method for implementing image cropping within themes. It is one of the most robust image cropping tools with zero dependencies. We also pair this with Compressor.js in order to squeeze the most out of our files before they get uploaded to the server. Providing you with piece of mind that image are small in size without sacrificing quality.
Supported Templates
The following page types support the use of the image cropper:
Signup Edit
Petition
Endorsement
Suggestion Box
Requirements
A v3 or above theme as the base:
- Momentum
- Raise (Note: You will need to either not use the file dropzone or retool it to work with the cropper on your own)Base theme (Bootstrap 4)
Modern browser; there are fallbacks for IE11 which treats the uploader as a normal file uploader
Usage
Here is a very basic implementation of ImgCropper using a standard Bootstrap modal component.
Step 1
In a supported template add a class of .img-cropper to the file input field.
Add or make note of where you want the cropped preview to show. In the example below we use an empty element: <div id="previewImg"></div>
<form class="ajaxForm">
<input type="file" class="img-cropper" name="profile_photo" />
<div id="previewImg"></div>
<div class="modal fade" id="cropModal" tabindex="-1" role="dialog" aria-labelledby="modalLabel" aria-hidden="true">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="modalLabel">Crop the image</h5>
<button type="button" class="close" data-dismiss="modal" aria-label="Close">
<span aria-hidden="true">×</span>
</button>
</div>
<div class="modal-body">
<div class="img-container mb-3">
<img id="image" class="img-cropper__placeholder invisible" src="data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs%3D" width="640" height="480" />
</div>
</div>
<div class="modal-footer justify-content-start">
<button type="button" class="btn btn-primary img-cropper__submit-btn">Crop</button>
<button type="button" class="btn btn-secondary" data-dismiss="modal">Cancel</button>
</div>
</div>
</div>
</div>
</form>
Step 2
Add {{ img_cropper_js }} to your layout.html template
In your theme’s JavaScript, add the following to initialize the cropper.
Example liquid tag to pull in the cropper JavaScript and initialization of the plugin within the layout.html file
{{ img_cropper_js }}
<script>
$(document).ready(function () {
if ($('.img-cropper').length) {
var $cropModal = $('#cropModal');
var imgcrop = new ImgCropper({
previewImgSelector: '#previewImg',
previewImgClasses: ['mt-3', 'border', 'p-1', 'rounded'],
beforeCrop: function () { $cropModal.modal('show') },
afterCrop: function (cropCanvas) { $cropModal.modal('hide') }
});
imgcrop.init();
$cropModal.on('shown.bs.modal', function () {
imgcrop.create();
}).on('hidden.bs.modal', function () {
imgcrop.destroy();
});
}
});
</script>
Step 3
Add the cropper SCSS to your theme (download here)
Include the _image_cropper.scss file in your theme.scss file.
Options
The following options are available to users implementing the ImgCropper in their theme:
Option | Type | Description |
debug | Boolean Default: true | Will display console information useful for debugging |
aspectRatio | Number Default: 1 | This exposed option from Cropper.js allows you to set a default aspect ratio to your image crop. Since we are primarily concerned with user avatars we set it to be a 1:1 ratio |
viewMode | Number | See Cropper.js docs for regarding viewMode |
dragMode | String Default: ‘move’ ‘none’ ‘crop’ | See Cropper.js docs for regarding dragMode |
width | Number Default: 144 | A max width of 2800px is set for any image being processed |
height | Number Default: 144 | A max height of 2800px is set for any image being processed |
quality | Number Default: 0.95 | Defines the image quality based on the Compressor.js quality option |
placeholderSelector | String Default: '.img-cropper__placeholder' | Here you can define a different element selector for the image element where we will apply the Cropper.js plugin. This must be applied to an available <img/> in the DOM. |
fileInputSelector | String Default: '.img-cropper' | Here you can define a different element selector for the file input. Keep in mind it must be applied to an available input type of “file”. |
saveCropBtnSelector | String Default: '.img-cropper__submit-btn' | Here you can define a different element selector for the button that will trigger saving the crop. |
previewImgClasses | Array Default: [ ] | Here you can add an array of classes you want applied to the final preview image that is generated from the crop. Useful if you want specific styling on the preview image like making it a circle instead of a square. |
previewImgSelector | String Default: null | Used to select an existing element on the page to drop the cropped image preview into. If not defined, ImgCropper adds it after the file input. |
onImageReady | Function | Runs when the image element defined in the placeholderSelector is loaded and ready |
beforeCrop | Function | Runs after an image has been selected from the file input |
afterCrop | Function(canvas) | Runs after a crop has been made when a user clicks the button defined by saveCropBtnSelector. This method also receives one parameter which will be the cropped canvas element coming from Cropper.js |
Methods
Method | Description |
init() | Sets up all the ImgCropper and all its event handlers |
create() | Creates a new Cropper.js object out of the selected image defined in the placeholderSelector option |
destroy() | Destroys the Cropper.js element defined in create() |