JavaScript Image Cropper UI, using Prototype & script.aculo.us

About

The JavaScript image cropper UI allows the user to crop an image using an interface with the same features and styling as found in commercial image editing software, and is is based on the Prototype JavaScript framework and script.aculo.us. Initially I performed quite a lot of searching for some ready made solutions to meet my requirements, but found none that had the complete feature set that I required or any complete versions based on Prototype.

So after a week and a half of work, I present the JavaScript image cropper UI, built on Prototype & script.aculo.us.

Features

Screen shot of cropper in action

Usage

Extract to a directory of your choosing e.g. ‘scripts/cropper/’ and include the script and the required Prototype & script.aculo.us scripts:

<script type="text/javascript" src="scripts/cropper/lib/prototype.js" language="javascript"></script>
<script type="text/javascript" src="scripts/cropper/lib/scriptaculous.js?load=effects,builder,dragdrop" language="javascript"></script>
<script type="text/javascript" src="scripts/cropper/cropper.js" language="javascript"></script>

Options

ratioDim obj

The pixel dimensions to apply as a restrictive ratio, with properties x & y.

minWidth int

The minimum width for the select area in pixels.

minHeight int

The mimimum height for the select area in pixels.

maxWidth int

The maximum width for the select areas in pixels (if both minWidth & maxWidth set to same the width of the cropper will be fixed)

maxHeight int

The maximum height for the select areas in pixels (if both minHeight & maxHeight set to same the height of the cropper will be fixed)

displayOnInit int

Whether to display the select area on initialisation, only used when providing minimum width & height or ratio.

onEndCrop func

The callback function to provide the crop details to on end of a crop.

captureKeys boolean

Whether to capture the keys for moving the select area, as these can cause some problems at the moment.

onloadCoords obj

A coordinates object with properties x1, y1, x2 & y2; for the coordinates of the select area to display onload

The callback function

The callback function is a function that allows you to capture the crop co-ordinates when the user finished a crop movement, it is passed two arguments:

An example function which outputs the crop values to form fields:

function onEndCrop( coords, dimensions ) {
  $( 'x1' ).value = coords.x1;
  $( 'y1' ).value = coords.y1;
  $( 'x2' ).value = coords.x2;
  $( 'y2' ).value = coords.y2;
  $( 'width' ).value = dimensions.width;
  $( 'height' ).value = dimensions.height;
}

Basic interface

This basic example will attach the cropper UI to the test image and return crop results to the provided callback function.

<img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />

<script type="text/javascript" language="javascript">
  Event.observe( window, 'load', function() {
    new Cropper.Img(
      'testImage',
      { onEndCrop: onEndCrop }
    );
  } );
</script>

Minimum dimensions

You can apply minimum dimensions to a single axis or both, this example applies minimum dimensions to both axis.

<img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />

<script type="text/javascript" language="javascript">
  Event.observe( window, 'load', function() {
    new Cropper.Img(
      'testImage',
      {
        minWidth: 220,
        minHeight: 120,
        onEndCrop: onEndCrop
      }
    );
  } );
</script>

Select area ratio

You can apply a ratio to the selection area, this example applies a 4:3 ratio to the select area.

<img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />

<script type="text/javascript" language="javascript">
  Event.observe( window, 'load', function() {
    new Cropper.Img(
      'testImage',
      {
        ratioDim: {
          x: 220,
          y: 165
        },
        displayOnInit: true,
        onEndCrop: onEndCrop
      }
    );
  } );
</script>

With crop preview

You can display a dynamically produced preview of the resulting crop by using the ImgWithPreview subclass, a preview can only be displayed when we have a fixed size (set via minWidth & minHeight options). Note that the displayOnInit option is not required as this is the default behaviour when displaying a crop preview.

<img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
<div id="previewWrap"></div>

<script type="text/javascript" language="javascript">
  Event.observe( window, 'load', function() {
    new Cropper.ImgWithPreview(
      'testImage',
      {
        previewWrap: 'previewWrap',
        minWidth: 120,
        minHeight: 120,
        ratioDim: { x: 200, y: 120 },
        onEndCrop: onEndCrop
      }
    );
  } );
</script>

Known Issues