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">&times;</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()

Did this answer your question?