You are viewing Jcrop 2.x documentation — click here for legacy v0.9.x

Jcrop Quickstart Guide

Before we start...

Let's make sure we're on the same page. You'll need the following things:

  • An HTML page or website
  • Basic understanding of web building concepts
  • A few minutes of your time

What this document covers

  • Including the necessary scripts and stylesheets on your page
  • Attaching Jcrop using the jQuery plugin method
  • How to specify Jcrop options
  • Listening for events
  • Basic <form> integration

Including Jcrop

First, we need to load a few assets on our page:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="http://jcrop-cdn.tapmodo.com/v2.0.0-RC1/js/Jcrop.js"></script>
<link rel="stylesheet" href="http://jcrop-cdn.tapmodo.com/v2.0.0-RC1/css/Jcrop.css" type="text/css">

You have two options for doing this:

Having trouble? Make sure all three files are being included successfully.
That means no 404 errors, and don't forget to include jQuery!

Attaching Jcrop

Let's assume there is an image on the page:

<img src="photo.jpg" id="target" />

Are you ready to do this? Insert the following script on your page:

<script type="text/javascript">
  jQuery(function($)){
  
    $('#target').Jcrop();
    
  });
</script>

Recognize this pattern? Most developers will already be familiar with the jQuery DOM-ready callback.
Further examples on this site will omit the DOM-ready and script tag wrappers, but don't forget them!

Specifying Options

Like most jQuery plugins, the Jcrop plugin accepts an options object as the first parameter.

$('#target').Jcrop({
  setSelect: [ x,y,w,h ],
  aspectRatio: 1,
  bgColor: 'red'
});
  • Any Jcrop option can be specified at startup, to configure how the Jcrop instance will behave.
  • Subsequent calls with options object passed to a running instance will perform setOptions.
  • Recommended to always include an initial selection area with setSelect option.
  • Never put a comma after the last value!

Listening for Events

At this point we have included the necessary Javascript and CSS files in our document, and attached Jcrop to an image element. If all went well, Jcrop is now attached to the image and cropping can commence.

Now bind some event listeners to get updates when the Jcrop selection changes:

$('#target').on('cropstart cropmove cropend',function(e,s,c){

  console.log(e,s,c);
  // @todo: do something useful with c
  // { x: 10, y: 10, x2: 30, y2: 30, w: 20, h: 20 }
  // c.x, c.y, c.w, c.h, ...
  // or access s.selectionApiMethod() or s.core.apiMethod() etc
  // compare event type with e.type (e.g. in if conditional, switch block)

});

As you can see, we are not doing much yet.

Basic <form> integration

The easiest way to get cropping coordinates onto your server is to fill <input> values in a pre-existing form:

<form action="save.php" id="myform">
  <input type="hidden" name="cropx" id="cropx" value="0" />
  <input type="hidden" name="cropy" id="cropy" value="0" />
  <input type="hidden" name="cropw" id="cropw" value="0" />
  <input type="hidden" name="croph" id="croph" value="0" />
  <input type="submit" value="Save Coordinates" />
</form>

In your script, add an event handler to fill the form:

$('#target').on('cropmove cropend',function(e,s,c){
  $('#cropx').val(c.x);
  $('#cropy').val(c.y);
  $('#cropw').val(c.w);
  $('#croph').val(c.h);
});

Now we are getting somewhere:

  • When the selection is altered, the form values are filled automatically.
  • When the submit button is clicked, the form values will be posted.

Controlling Behavior

In the previous section, the form contained hidden form elements. Suppose we wanted to allow the user to edit them, and update the selection in Jcrop.

Change the form a little bit:

<form id="myform" onsubmit="return false;">
  <input type="text" name="cropx" id="cropx" value="0" />
  <input type="text" name="cropy" id="cropy" value="0" />
  <input type="text" name="cropw" id="cropw" value="0" />
  <input type="text" name="croph" id="croph" value="0" />
</form>

Add handler to form element:

$('#myform').on('change','[type=text]',function(e){

  $('#target').Jcrop('api').setSelect([
    parseInt($('#cropx').val()),
    parseInt($('#cropy').val()),
    parseInt($('#cropw').val()),
    parseInt($('#croph').val())
  ]);

});

This is a very rudimentary example, but it gives a first glimpse of what can be accomplished using the API.

Further Reading

Congratulations! You've reached the end of the Jcrop Quickstart Guide. We've covered the basics in just a few minutes, but there's a lot more to learn if you really want to get your hands dirty. Here are a few topics you might want to read next: