Announcement: V2 plans & fund raising
Please take a moment to read my plans for version 2 of the cropper and how you can support it.
Details
| Version | 1.2.0 |
|---|---|
| Last updated | 30th October 2006 |
| Requirements |
|
| Demo | View demo page |
| Links | |
| License | BSD License |
| Changelog |
|
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
![]()
- Un-obtrusive
- Based on Prototype and script.aculo.us
- Image editing package styling & functionality, the crop area functions and looks like those found in popular image editing software
- Dynamic inclusion of required styles
- Drag to draw areas
- Shift drag to draw/resize areas as squares
- Selection area can be moved
- Selection area can be resized using resize handles
- Allows dimension ratio limited crop areas
- Allows minimum dimension crop areas
- Allows maximum dimensions crop areas, if both min & max set as the same value then we'll get a fixed cropper size on the axes as appropriate and the resize handles will not be displayed as appropriate
- Allows dynamic preview of resultant crop (if minimum width & height are provided), this is implemented as a subclass so can be removed if not required
- Movement of selection area by arrow keys (shift + arrow key will move selection area by 10 pixels)
- All operations stay within bounds of image
- All functionality & display compatible with most popular browsers supported by Prototype, tested in:
- PC: IE 6 & 5.5, Firefox 1.5, Opera 8.5 (see known issues) & 9.0b
- MAC: Camino 1.0, Firefox 1.5, Safari 2.0
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=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:
- coords, obj, coordinates object with properties x1, y1, x2 & y2; for the coordinates of the select area.
- dimensions, obj, dimensions object with properities width & height; for the dimensions of the select area.
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.
Minimum dimensions
You can apply minimum dimensions to a single axis or both, this example applies minimum dimensions to both axis.
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
- Safari animated gifs, only one of each will animate, this seems to be a known Safari issue.
- After drawing an area and then clicking to start a new drag in IE 5.5 the rendered height appears as the last height until the user drags, this appears to be the related to another IE error (which has been fixed) where IE does not always redraw the select area properly.
- Lack of CSS opacity support in Opera before version 9 mean we disable those style rules, if Opera 8 support is important you & you want the overlay to work then you can use the Opera rules in the CSS to apply a black PNG with 50% alpha transparency to replicate the effect.
- Styling & borders on image, any CSS styling applied directly to the image itself (floats, borders, padding, margin, etc.) will cause problems with the cropper. The use of a wrapper element to apply these styles to is recommended.
- overflow: auto or overflow: scroll on parent will cause cropper to burst out of parent in IE and Opera when applied (maybe Mac browsers too) I'm not sure why yet.
Other Links: SEO Agency advanced JavaScript experience can enhance your site functionality. Adding the JavaScript Image Cropper is a good way to improve the user experience.
Next Steps
Feature Requests & Bug Reports
Please check the existing list of feature requests & bugs and the discussion list before posting requests or reporting bugs.
Leave a Tip
If you find this code useful you can leave a donation towards the continued development & support.
Announcement: V2 plans & fund raising
Please take a moment to read my plans for version 2 of the cropper and how you can support it.

Comments
There have been 494 comments so far, join the discussion.
Pages: « 25 … 23 22 21 20 19 [18] 17 16 15 14 13 … 1 » Show All
360. Dave Schlaegel - 15th Oct 2007 - 3:08 pm
leonidas: Not sure if you where talking to me or not, but I put the code I used for multiple crops per page on my last comment. It works perfect for me, I have 100 images loading on a page all with crop, all submit with the correct crop values. Plus I didn’t change much at all to the code really, just sending the image id back in the callback, and setting the field updates to use the image id. Let me know if you didn’t understand what I did I will try to explain better.
359. leonidas - 15th Oct 2007 - 2:49 pm
Amazing! Thank you, Dave!
I wonder if “Frank” ever finalized his plan – multiple crops on one image. That’s exactly what i would require now, but i can’t seem to get there – at least not without patching the whole code – which would be far off my project deadline. Anyway, i wanted to ask if you could interconnect me with “Frank” to find out how he managed that problem. Or maybe you have a suggestion?
Kind regards, leonidas
358. Nick1234 - 15th Oct 2007 - 1:54 pm
Can anybody help me turn this into a profile picture tumbnail maker – like the one on facebook – thanks
357. Dave - 15th Oct 2007 - 8:52 am
Matthew:
I’m glad you found it useful, hopefully it saved you a lot of time hacking around with other scripts.
356. Matthew - 15th Oct 2007 - 8:37 am
Amazing script. I considered three or four other scripts, got about half way through customizing most (and completely finished one), when I came across this. Ditched everything else and went full-speed using your Cropper and, my goodness, it’s perfect.
The cropping tool is now live and in-use by everyone at my site. Thank you SO MUCH for putting this out, and especially under the BSD.
355. kevin - 14th Oct 2007 - 11:25 am
Sorry, that didnt paste in too well!
It’s at http://solomon.ie/onEndCrop.txt if anyone wants it
354. kevin - 14th Oct 2007 - 11:20 am
Firstly, many thanks for such a great script!
One thing I wanted to do was submit the xy values to my server side cropping script via a hidden form on double click of the crop area and saw that someone asked the same thing so I made a mod to do that.
Basically it works on the bases that onEndCrop() gets called every time you click, so I modified it to detect a double click and submit my form.
var TimeOfLastClick =0; // init at page load
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;
// get time of this click in milseconds
var thisClick=new Date();
var thisClickMs = thisClick.getTime();
// if this click happened within 300ms of last one it’s
// a double click so submit a form named ‘cropform’
if ((thisClickMs – TimeOfLastClick)
353. Dave Schlaegel - 12th Oct 2007 - 5:36 pm
Great peice of code!
Slightly modifed to allow multiple img cropps per page.
My usage of it requires multiple images to be cropped per page. Its an admin function for my site so I can crop hundreds of images on one page.
I added the image id to the callback function. And use the image id to identify the image being edited to update the correct text fields.
So modifed the callback line in cropper.js to:
this.options.onEndCrop(this.img.id, this.areaCoords,{width:this.calcW(),height:this.calcH()});
The callback function I just changed to use the img id to identify which text fields to update:
function onEndCrop( img_id, coords, dimensions ) {
$( ‘x1_’+img_id).value = coords.x1;
$( ‘y1_’+img_id).value = coords.y1;
$( ‘x2_’+img_id).value = coords.x2;
$( ‘y2_’+img_id).value = coords.y2;
$( ‘width_’+img_id).value = dimensions.width;
$( ‘height_’+img_id).value = dimensions.height;
}
Very simple if you need to crop allow of images per page.
352. rapra - 12th Oct 2007 - 4:48 pm
by changing image src propoerty by javascript. in browser new image is loading in cropping window, but not in preview window.
I have any idea how to reload window in preview window too?
Anyone would help?
rapra
351. rapra - 12th Oct 2007 - 4:45 pm
good spcript, but I have a problem:
I am loading a page with empty field. I choosed cropping with preview.
I am choosing an image with input type=”file” field and onChange I am loading choosed by file field image into by changing
350. Ashish Bhawnani - 11th Oct 2007 - 1:25 pm
hi Dave,
It does exactly what I need it to do, thank you very much
it is working perfectly fine, also easy to understand, i use it in my asp.net project.
thanks once again.
349. MySchizoBuddy - 10th Oct 2007 - 8:23 am
Thanks. but that link is not in english language :S
348. Schleevoigt - 10th Oct 2007 - 7:38 am
If you want to transfer the cropping dates to PHP you can use the following way.
1. onevent read hidden form elements in which are the coords
2. calling ajax to transfer it to the server
Here is an example:
http://familientagebuch.de/rainer/2006/50.html#5
With this variant you cal also crop the image with imagemagick (convert)
347. MySchizoBuddy - 10th Oct 2007 - 7:20 am
How do i pas the crop parameters to PHP?
I’m looking at using phpthumb and your javascript Cropper UI to send crop parameters to phpthumb.
Thankyou
346. Sergey K. - RMT Image Cropper - 9th Oct 2007 - 6:46 pm
It was discussed many times, what Javascript can’t handle or process images, only server side script like PHP, asp or any other. Look for more details or tutorials in search englines.
345. otak - 9th Oct 2007 - 2:04 pm
Does anyone have a javascript code to save a cropped image?
344. Raker - 8th Oct 2007 - 8:40 pm
Hi,
i have a question about a cropper.
It is possible to use dinamic image change and image preview function?
If ‘YES’ can U tell me how i can do this?
Raker
343. John Perry - 6th Oct 2007 - 3:27 am
Hello,
Just wanted to say awesome tool! It does exactly what I need it to do. But I am having an issue. IM on IE 6 and what IM doing is IM grabbing the coordinates using your tool and putting it into a form on the same page. I then submit the form via post and using PHP I store the information in a database. The problem is when the page refreshes the image is blank. I have to hit refresh for it to show up again. If I go to IE options and choose look for a new version on every visit instead of automatically then it works just fine. Any suggestions?
342. Robert McIlreavy - 5th Oct 2007 - 1:27 pm
I really like this but i’m not sure if this can be done or not. Is it possible to save the preview picture as a image in a directory?? any help would be great.
341. Nick - 5th Oct 2007 - 11:52 am
Thanks Dave for your quick response!
So far I have managed to update the textboxes whilst resizing by adding to onDrag (had to use 1.5.0 final of prototype), now for when you move the selection around. I’m slightly unsure where this function is?
Also if I wanted to type values in the textboxes and have them displayed would I use setAreaCoords?
Thanks for your time!
Leave a comment
No HTML please, only textile. For code please use [lang]...[/lang] tags (e.g. [html]...[/html] for HTML)